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

Make messaging trees atomic ownership boundaries (#1048)

Ali Khokhar2bcaf3ac743d
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index c5031d86..d3975ab2 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -122,6 +122,11 @@ compatibility shims, endpoints, or helper paths that do not serve one of the
surfaces above are not product requirements and should be removed rather than
preserved.
+The supported messaging extension surface consists of transport ingress values,
+platform ports, and managed-session protocols. Tree aggregates, processors,
+repositories, transition values, and package-level re-exports of those
+implementation types are internal; they are not a versioned Python SDK surface.
+
## Design Pressure And Refactor Targets
The current package boundaries are intentional, but several modules still carry
@@ -783,7 +788,9 @@ Shared voice-note orchestration lives in
pending voice registration, file-size validation, temp-file cleanup,
transcription, cancellation, error replies, and the handoff to
`IncomingMessage`. It depends only on the consumer-owned `Transcriber` protocol
-from [messaging/voice.py](src/free_claude_code/messaging/voice.py). Bootstrap selects either the
+from [messaging/voice.py](src/free_claude_code/messaging/voice.py). Pending voice lookups use the
+same `(platform, chat_id)` `MessageScope` as tree references, so raw IDs from
+different transports cannot share cancellation ownership. Bootstrap selects either the
instance-owned local Whisper `TranscriptionService` or the provider-owned
`NvidiaNimTranscriber`. Messaging no longer imports a provider adapter, and the
local service retains only one lazy pipeline for its immutable runtime settings;
@@ -795,19 +802,36 @@ restart-required, while the same provider credential remains hot-replaceable
when voice does not use it.
[messaging/workflow.py](src/free_claude_code/messaging/workflow.py) contains `MessagingWorkflow`, the
-platform-agnostic coordinator. It owns dependencies, callback wiring, stop/clear
-side effects, render settings, and shutdown-visible state.
+platform-agnostic coordinator. It owns dependencies, render settings, the
+state-transaction lock, admission epoch, stop/clear side effects, and
+shutdown-visible state. Each inbound turn snapshots the epoch before external
+status I/O and rechecks it while committing admission; global `/stop` and
+`/clear` advance the epoch so an older provisional turn is discarded instead of
+crossing that boundary. The workflow persists the detached snapshot returned by
+the same transition instead of taking a later mutable-node read. Once a stop or
+clear transition commits, its persistence effects are applied before the later
+interruptible global CLI cleanup. At startup it restores and normalizes
+persisted state before ingress begins, then repairs interrupted platform
+statuses after outbound delivery starts.
[messaging/turn_intake.py](src/free_claude_code/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.
+recording, slash command dispatch, status-echo filtering, initial status
+messages, and rendering detached frozen admission/queue effects. It asks the workflow
+to resolve and admit turns rather than receiving a mutable tree. Reply lookup is
+always scoped by platform and chat; an unknown or cross-chat reference cannot
+attach to another tree and therefore starts an independent root. If duplicate
+delivery or an epoch change rejects admission after a provisional status was
+sent, intake deletes that status and removes it from the message log.
[messaging/node_runner.py](src/free_claude_code/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. Runner persistence must be guarded by active tree
-membership so late cancellation cleanup cannot restore state after `/clear`
-removed a tree or reset the queue.
+and session cleanup. It executes an immutable `NodeClaim`; session, completion,
+and failure writes return through `TreeQueueManager` with that claim identity. A
+non-exit CLI error may render an error immediately, but only a terminal failure
+propagates to queued descendants; a later successful exit is authoritative for
+the same live, non-cancelled claim. A stale runner receives no snapshot and
+cannot restore a branch removed by `/clear`.
[messaging/event_parser.py](src/free_claude_code/messaging/event_parser.py) normalizes managed Claude
JSON events into low-level transcript events.
@@ -820,29 +844,79 @@ models, render context, and truncation. Platform markdown details stay in
dependency surface for `/stop`, `/clear`, and `/stats`; commands should not
depend on the concrete workflow object or on platform SDK runtimes.
-[messaging/trees/manager.py](src/free_claude_code/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. Tree cancellation is terminal: cancelling `/stop`, reply
-`/stop`, reply `/clear`, or global `/clear` awaits active task cleanup outside
-tree locks before command state cleanup continues.
+[messaging/trees/runtime.py](src/free_claude_code/messaging/trees/runtime.py) contains the
+`MessageTree` aggregate. Its lock is private, and complete operations own every
+graph/queue/claim invariant: add-and-admit, enqueue-or-claim,
+finish-and-claim-next, semantic state writes, cancellation, and atomic branch
+removal. `TreeIdentity` is `(platform, chat_id, root_message_id)`, because
+platform message IDs are not globally unique. Every execution receives a fresh
+opaque claim ID, so a task from an older runtime generation cannot mutate or
+collide with a re-admitted tree. Active execution ownership is separate from the
+node's UI state: cancellation can still reach a task that already rendered
+complete/error but is cleaning up, while a cancellation tombstone prevents late
+success from reviving a stopped node. Only the matching finish transition may
+select the FIFO successor. Duplicate node/status admission and terminal-node
+re-admission are rejected without changing active state.
+
+[messaging/trees/transitions.py](src/free_claude_code/messaging/trees/transitions.py) owns frozen,
+slotted claims, queue entries, read views, and cancellation/removal effects.
+These values copy the UI and execution facts callers need and never contain a
+mutable `MessageNode`, lock, or `asyncio.Task`.
+
+[messaging/trees/manager.py](src/free_claude_code/messaging/trees/manager.py) is the only external
+tree facade. It keeps one structural lock across aggregate membership changes
+and repository index publication/removal, registers node and status references
+together under `MessageScope`, coordinates cross-tree requests, and returns
+transition-owned snapshots. Claim completion re-enters that same lock: the
+manager verifies the exact aggregate is still published and publishes any
+successor task slot before a competing detach can commit. Cancellation and
+removal entrypoints finish their exact transition despite caller cancellation,
+so a committed detach cannot lose its UI or persistence result. Reply `/clear`
+is one cancel-and-detach transition before platform I/O; global clear atomically
+detaches every aggregate before
+task draining. Reply `/stop` cancels exactly one request; its matching finisher
+releases execution ownership and advances the next eligible queued request.
+Global `/stop` drains every queue instead, and reply `/clear` removes the whole
+selected branch before any survivor can advance. Separate trees still progress
+independently.
[messaging/trees/repository.py](src/free_claude_code/messaging/trees/repository.py)
-owns the in-memory tree/node index, and
-[messaging/trees/processor.py](src/free_claude_code/messaging/trees/processor.py) owns async queue
-processing. [messaging/trees/node.py](src/free_claude_code/messaging/trees/node.py) owns
-`MessageNode` and `MessageState`,
+is manager-private and owns only aggregate/reference indexes.
+[messaging/trees/processor.py](src/free_claude_code/messaging/trees/processor.py) owns every
+`asyncio.Task`, keyed by globally unique claim ID. It publishes a task slot
+before task creation, which is safe under Python's eager task factory, then
+launches claims returned by the aggregate, cancels the exact matching task,
+drains cleanup outside tree locks, and feeds matching completion back to the
+aggregate. Cancellation before a task body starts has an explicit recovery path;
+the cancellation flag is rechecked after callbacks, and callback failure cannot
+prevent successor launch. If a node processor unexpectedly escapes, the
+processor routes failure through the manager-owned aggregate transition; the
+workflow persists its snapshot and schedules its UI effect as normal queue
+advancement continues. [messaging/trees/node.py](src/free_claude_code/messaging/trees/node.py) owns
+`MessageNode` and `MessageState`; each node keeps only the copied scope and
+prompt needed by the aggregate rather than retaining a mutable ingress value,
[messaging/trees/graph.py](src/free_claude_code/messaging/trees/graph.py) owns parent/child and
-status-message lookup state, [messaging/trees/runtime.py](src/free_claude_code/messaging/trees/runtime.py)
-owns locks/current-task/processing state, and
+status-message lookup state, and
[messaging/trees/snapshot.py](src/free_claude_code/messaging/trees/snapshot.py) owns typed persisted
-conversation snapshots.
+conversation snapshots. New snapshots serialize scoped trees as a list, while
+loading derives scope from existing pre-scope `sessions.json` tree roots. Nodes
+persist only their canonical parent relation; runtime child indexes are rebuilt
+on restore, and transport ingress payloads do not leak into aggregate storage.
+A malformed tree carrying neither current scope nor legacy root ingress is
+reported and skipped because assigning it to an inferred chat would violate the
+same ownership boundary.
[messaging/session/](src/free_claude_code/messaging/session/) persists typed conversation snapshots
and message IDs to a JSON file under the managed agent workspace.
`SessionStore` reads existing `sessions.json` files but exposes typed snapshot
-APIs to runtime code. Debounced atomic writes live in
-[messaging/session/persistence.py](src/free_claude_code/messaging/session/persistence.py), and
-per-chat message ID tracking for `/clear` lives in
+APIs to runtime code and deep-copies snapshot ingress and egress so no caller
+shares mutable persisted state. Debounced atomic writes live in
+[messaging/session/persistence.py](src/free_claude_code/messaging/session/persistence.py). One writer
+lock serializes physical replaces, and a generation check under that lock
+prevents an older timer snapshot from landing after a newer flush or clear.
+Global `/clear` performs an early authoritative wipe, detaches and drains every
+tree, then writes an authoritative empty conversation snapshot while preserving
+message IDs recorded after the early wipe.
+Per-chat message ID tracking for `/clear` lives in
[messaging/session/message_log.py](src/free_claude_code/messaging/session/message_log.py). `/clear`
guarantees FCC state cleanup and tries tracked platform deletes through the
list-based outbound delete port, but Discord/Telegram can still reject
diff --git a/README.md b/README.md
index 00a9ddb0..c36a1f56 100644
--- a/README.md
+++ b/README.md
@@ -306,7 +306,10 @@ Configure integrations from **Admin UI → Messaging**, then click **Validate**
</details>
-Bot commands: `/stop` cancels work, `/clear` resets sessions, and `/stats` shows session state. Reply to a task message to target only that conversation branch.
+Bot commands: standalone `/stop` cancels all work, standalone `/clear` resets all
+sessions, and `/stats` shows session state. Reply with `/stop` to cancel only
+that request while other queued requests continue. Reply with `/clear` to
+remove that conversation branch.
<details>
<summary><strong>Voice notes</strong></summary>
diff --git a/pyproject.toml b/pyproject.toml
index 93f161a7..600517e7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "3.4.22"
+version = "3.4.23"
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 738069d2..17a8985d 100644
--- a/smoke/capabilities.py
+++ b/smoke/capabilities.py
@@ -378,6 +378,11 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
(
"tests/messaging/test_handler.py",
"tests/messaging/test_handler_integration.py",
+ "tests/messaging/test_tree_ownership_concurrency.py",
+ ),
+ (
+ "test_messaging_commands_stop_clear_stats_e2e",
+ "test_messaging_queued_scoped_cancel_e2e",
),
),
CapabilityContract(
@@ -391,6 +396,13 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
(
"tests/messaging/test_tree_queue.py",
"tests/messaging/test_tree_concurrency.py",
+ "tests/messaging/test_message_tree_transitions.py",
+ "tests/messaging/test_tree_ownership_concurrency.py",
+ ),
+ (
+ "test_tree_threading_e2e",
+ "test_messaging_queued_scoped_cancel_e2e",
+ "test_same_message_ids_are_isolated_by_chat_e2e",
),
),
CapabilityContract(
@@ -399,7 +411,7 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
"restart_restore",
"free_claude_code.messaging.session.SessionStore",
"stored tree JSON",
- "restored node-to-tree mapping",
+ "restored scoped reply lookup",
"stale pending work marked lost",
("tests/messaging/test_restart_reply_restore.py",),
),
@@ -408,7 +420,7 @@ CAPABILITY_CONTRACTS: tuple[CapabilityContract, ...] = (
"session_store",
"session_persistence",
"free_claude_code.messaging.session.SessionStore",
- "tree data, node mapping, and message log",
+ "scoped tree data and message log",
"JSON persistence compatible with existing files",
"best-effort flush error logging",
("tests/messaging/test_session_store_edge_cases.py",),
diff --git a/smoke/features.py b/smoke/features.py
index 08c2828c..16ba1ef0 100644
--- a/smoke/features.py
+++ b/smoke/features.py
@@ -439,9 +439,13 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
(
"tests/messaging/test_handler.py",
"tests/messaging/test_handler_integration.py",
+ "tests/messaging/test_tree_ownership_concurrency.py",
),
(),
- ("test_messaging_commands_stop_clear_stats_e2e",),
+ (
+ "test_messaging_commands_stop_clear_stats_e2e",
+ "test_messaging_queued_scoped_cancel_e2e",
+ ),
("messaging",),
(),
"required fake-platform product flow",
@@ -453,9 +457,15 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
(
"tests/messaging/test_tree_queue.py",
"tests/messaging/test_tree_concurrency.py",
+ "tests/messaging/test_message_tree_transitions.py",
+ "tests/messaging/test_tree_ownership_concurrency.py",
),
(),
- ("test_tree_threading_e2e",),
+ (
+ "test_tree_threading_e2e",
+ "test_messaging_queued_scoped_cancel_e2e",
+ "test_same_message_ids_are_isolated_by_chat_e2e",
+ ),
("messaging",),
(),
"required fake-platform product flow",
@@ -473,7 +483,7 @@ FEATURE_INVENTORY: tuple[FeatureCoverage, ...] = (
),
FeatureCoverage(
"session_persistence",
- "Session JSON preserves trees, node mapping, and message logs",
+ "Session JSON preserves scoped trees and message logs",
"public_surface",
("tests/messaging/test_session_store_edge_cases.py",),
(),
diff --git a/smoke/lib/e2e.py b/smoke/lib/e2e.py
index d90f4415..beee97c8 100644
--- a/smoke/lib/e2e.py
+++ b/smoke/lib/e2e.py
@@ -25,7 +25,7 @@ from free_claude_code.core.anthropic.stream_contracts import (
parse_sse_lines,
text_content,
)
-from free_claude_code.messaging.models import IncomingMessage
+from free_claude_code.messaging.models import IncomingMessage, MessageScope
from free_claude_code.messaging.session import SessionStore
from free_claude_code.messaging.workflow import MessagingWorkflow
from smoke.lib.child_process import run_captured_text
@@ -318,7 +318,7 @@ class FakePlatform:
self.deletes: list[dict[str, Any]] = []
self._counter = 0
self._tasks: list[asyncio.Future[Any]] = []
- self._pending_voice: dict[tuple[str, str], tuple[str, str]] = {}
+ self._pending_voice: dict[tuple[MessageScope, str], tuple[str, str]] = {}
async def start(self) -> None:
return None
@@ -340,6 +340,10 @@ class FakePlatform:
def on_message(self, handler: Callable[[IncomingMessage], Awaitable[None]]) -> None:
self.handler = handler
+ def continue_message_sequence_after(self, previous: FakePlatform) -> None:
+ """Model platform-owned message IDs surviving an FCC restart."""
+ self._counter = previous._counter
+
async def emit(self, incoming: IncomingMessage) -> None:
assert self.handler is not None
await self.handler(incoming)
@@ -428,15 +432,16 @@ class FakePlatform:
def register_pending_voice(
self, chat_id: str, voice_message_id: str, status_message_id: str
) -> None:
- self._pending_voice[(chat_id, voice_message_id)] = (
+ scope = MessageScope(platform=self.name, chat_id=chat_id)
+ self._pending_voice[(scope, voice_message_id)] = (
voice_message_id,
status_message_id,
)
async def cancel_pending_voice(
- self, chat_id: str, reply_id: str
+ self, scope: MessageScope, reply_id: str
) -> tuple[str, str] | None:
- return self._pending_voice.pop((chat_id, reply_id), None)
+ return self._pending_voice.pop((scope, reply_id), None)
class FakeCLISession:
@@ -523,33 +528,51 @@ class FakePlatformDriver:
self,
text: str,
*,
+ chat_id: str = "chat_1",
+ message_id: str | None = None,
+ reply_to: str | None = None,
+ ) -> IncomingMessage:
+ incoming = await self.emit(
+ text,
+ chat_id=chat_id,
+ message_id=message_id,
+ reply_to=reply_to,
+ )
+ await self.wait_for_idle()
+ return incoming
+
+ async def emit(
+ self,
+ text: str,
+ *,
+ chat_id: str = "chat_1",
message_id: str | None = None,
reply_to: str | None = None,
) -> IncomingMessage:
+ """Deliver a message without waiting for background claims to finish."""
incoming = IncomingMessage(
text=text,
- chat_id="chat_1",
+ chat_id=chat_id,
user_id="user_1",
message_id=message_id or f"in_{uuid.uuid4().hex[:8]}",
platform=self.platform_name,
reply_to_message_id=reply_to,
)
await self.platform.emit(incoming)
- await self.wait_for_idle()
return incoming
async def wait_for_idle(self, *, timeout_s: float = 5.0) -> None:
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
pending = [task for task in self.platform._tasks if not task.done()]
- if not pending and self._all_tree_nodes_terminal():
+ if not pending and await self._all_tree_nodes_terminal():
self.session_store.flush_pending_save()
return
await asyncio.sleep(0.02)
raise AssertionError("fake platform did not become idle")
- def _all_tree_nodes_terminal(self) -> bool:
- snapshot = self.workflow.tree_queue.snapshot()
+ async def _all_tree_nodes_terminal(self) -> bool:
+ snapshot = await self.workflow.tree_queue.snapshot()
for tree in snapshot.trees.values():
for node in tree.nodes.values():
if node.get("state") in {"pending", "in_progress"}:
diff --git a/smoke/product/test_messaging_product_live.py b/smoke/product/test_messaging_product_live.py
index 678964f7..7122effa 100644
--- a/smoke/product/test_messaging_product_live.py
+++ b/smoke/product/test_messaging_product_live.py
@@ -1,9 +1,10 @@
+import asyncio
import json
import pytest
-from free_claude_code.messaging.trees import MessageState
-from smoke.lib.e2e import FakePlatformDriver, default_cli_events
+from free_claude_code.messaging.trees import MessageState, TreeIdentity
+from smoke.lib.e2e import FakeCLISession, FakePlatformDriver, default_cli_events
pytestmark = [pytest.mark.live, pytest.mark.smoke_target("messaging")]
@@ -15,9 +16,10 @@ 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.workflow.tree_queue.get_tree_for_node(incoming.message_id)
- assert tree is not None
- node = tree.get_node(incoming.message_id)
+ node = await driver.workflow.tree_queue.get_node(
+ incoming.scope,
+ incoming.message_id,
+ )
assert node is not None
assert node.state == MessageState.COMPLETED
assert driver.platform.sent
@@ -89,15 +91,116 @@ 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.workflow.tree_queue.get_tree_for_node(root.message_id)
- assert tree is not None
- branch_node = tree.get_node(branch.message_id)
+ branch_node = await driver.workflow.tree_queue.get_node(
+ branch.scope,
+ branch.message_id,
+ )
assert branch_node is not None
assert branch_node.parent_id == root.message_id
assert driver.cli_manager.sessions[1].calls[0]["session_id"] == "sess_root"
assert driver.cli_manager.sessions[1].calls[0]["fork_session"] is True
[email protected]("platform_name", ["discord", "telegram"])
+async def test_messaging_queued_scoped_cancel_e2e(
+ platform_name: str,
+ tmp_path,
+ monkeypatch,
+) -> None:
+ driver = FakePlatformDriver(platform_name, tmp_path)
+ root_started = asyncio.Event()
+ release_root = asyncio.Event()
+
+ class GatedRootSession(FakeCLISession):
+ async def start_task(
+ self,
+ prompt: str,
+ session_id: str | None = None,
+ fork_session: bool = False,
+ ):
+ self.calls.append(
+ {
+ "prompt": prompt,
+ "session_id": session_id,
+ "fork_session": fork_session,
+ }
+ )
+ self.is_busy = True
+ root_started.set()
+ try:
+ await release_root.wait()
+ for event in self.events:
+ await asyncio.sleep(0)
+ yield event
+ finally:
+ self.is_busy = False
+
+ async def controlled_session(session_id: str | None = None):
+ index = len(driver.cli_manager.sessions)
+ events = default_cli_events(f"sess_{index}")
+ session = GatedRootSession(events) if index == 0 else FakeCLISession(events)
+ driver.cli_manager.sessions.append(session)
+ return session, session_id or f"pending_{index}", session_id is None
+
+ monkeypatch.setattr(
+ driver.cli_manager,
+ "get_or_create_session",
+ controlled_session,
+ )
+
+ root = await driver.emit("root", message_id="root")
+ await root_started.wait()
+ cancelled = await driver.emit(
+ "cancel me",
+ message_id="cancelled",
+ reply_to=root.message_id,
+ )
+ survivor = await driver.emit(
+ "run me",
+ message_id="survivor",
+ reply_to=root.message_id,
+ )
+ await driver.emit(
+ "/stop",
+ message_id="stop-cancelled",
+ reply_to=cancelled.message_id,
+ )
+
+ release_root.set()
+ await driver.wait_for_idle()
+
+ prompts = [
+ call["prompt"]
+ for session in driver.cli_manager.sessions
+ for call in session.calls
+ ]
+ assert prompts == ["root", "run me"]
+ cancelled_view = await driver.workflow.tree_queue.get_node(
+ cancelled.scope,
+ cancelled.message_id,
+ )
+ survivor_view = await driver.workflow.tree_queue.get_node(
+ survivor.scope,
+ survivor.message_id,
+ )
+ assert cancelled_view is not None
+ assert cancelled_view.state is MessageState.ERROR
+ assert survivor_view is not None
+ assert survivor_view.state is MessageState.COMPLETED
+
+ rendered = "\n".join(
+ entry["text"] for entry in driver.platform.sent + driver.platform.edits
+ )
+ assert "position 1" in rendered
+ assert "position 2" in rendered
+ assert "Stopped" in rendered
+ driver.session_store.flush_pending_save()
+ persisted = driver.session_store.load_conversation_snapshot()
+ root_identity = TreeIdentity(scope=root.scope, root_id=root.message_id)
+ assert persisted.trees[root_identity].nodes["survivor"]["state"] == "completed"
+
+
@pytest.mark.asyncio
async def test_restart_restore_and_session_persistence_e2e(tmp_path) -> None:
first = FakePlatformDriver("telegram", tmp_path)
@@ -110,9 +213,54 @@ async def test_restart_restore_and_session_persistence_e2e(tmp_path) -> None:
assert payload["message_log"]
restored = FakePlatformDriver("telegram", tmp_path)
+ restored.platform.continue_message_sequence_after(first.platform)
+ restored.workflow.restore()
saved = restored.session_store.load_conversation_snapshot()
assert saved.trees
- assert root.message_id in saved.derive_node_to_tree()
+ identity = TreeIdentity(scope=root.scope, root_id=root.message_id)
+ assert saved.get_tree(identity) is not None
+
+ reply = await restored.send(
+ "continue from disk",
+ message_id="reply_1",
+ reply_to=root.message_id,
+ )
+ reply_view = await restored.workflow.tree_queue.get_node(
+ reply.scope,
+ reply.message_id,
+ )
+ assert reply_view is not None
+ assert reply_view.parent_id == root.message_id
+ call = restored.cli_manager.sessions[0].calls[0]
+ assert call["session_id"] == "fake_session_1"
+ assert call["fork_session"] is True
+
+
[email protected]("platform_name", ["discord", "telegram"])
+async def test_same_message_ids_are_isolated_by_chat_e2e(
+ platform_name: str,
+ tmp_path,
+) -> None:
+ driver = FakePlatformDriver(platform_name, tmp_path)
+ first = await driver.send("first chat", chat_id="chat_a", message_id="42")
+ second = await driver.send("second chat", chat_id="chat_b", message_id="42")
+
+ snapshot = await driver.workflow.tree_queue.snapshot()
+ assert set(snapshot.trees) == {
+ TreeIdentity(scope=first.scope, root_id="42"),
+ TreeIdentity(scope=second.scope, root_id="42"),
+ }
+
+ reply = await driver.send(
+ "first chat reply",
+ chat_id="chat_a",
+ message_id="43",
+ reply_to="42",
+ )
+ reply_view = await driver.workflow.tree_queue.get_node(reply.scope, "43")
+ assert reply_view is not None
+ assert reply_view.parent_id == "42"
@pytest.mark.asyncio
diff --git a/src/free_claude_code/messaging/__init__.py b/src/free_claude_code/messaging/__init__.py
index 224c89fd..13247d20 100644
--- a/src/free_claude_code/messaging/__init__.py
+++ b/src/free_claude_code/messaging/__init__.py
@@ -5,22 +5,18 @@ from .managed_protocols import (
ManagedClaudeSessionManagerProtocol,
ManagedClaudeSessionProtocol,
)
-from .models import IncomingMessage
+from .models import IncomingMessage, MessageScope
from .platforms.ports import OutboundMessenger
from .session import SessionStore
-from .trees import MessageNode, MessageState, MessageTree, TreeQueueManager
from .workflow import MessagingWorkflow
__all__ = [
"IncomingMessage",
"ManagedClaudeSessionManagerProtocol",
"ManagedClaudeSessionProtocol",
- "MessageNode",
- "MessageState",
- "MessageTree",
+ "MessageScope",
"MessagingWorkflow",
"OutboundMessenger",
"SessionStore",
- "TreeQueueManager",
"parse_cli_event",
]
diff --git a/src/free_claude_code/messaging/command_context.py b/src/free_claude_code/messaging/command_context.py
index 4dc65bb2..01d0bbca 100644
--- a/src/free_claude_code/messaging/command_context.py
+++ b/src/free_claude_code/messaging/command_context.py
@@ -3,10 +3,10 @@
from typing import Protocol
from .managed_protocols import ManagedClaudeSessionManagerProtocol
+from .models import MessageScope
from .platforms.ports import OutboundMessenger, VoiceCancellation
-from .session import SessionStore
from .transcript import RenderCtx
-from .trees import CancelledNode, MessageTree, TreeQueueManager
+from .trees import BranchRemovalResult
class MessagingCommandContext(Protocol):
@@ -15,10 +15,6 @@ class MessagingCommandContext(Protocol):
outbound: OutboundMessenger
voice_cancellation: VoiceCancellation | None
cli_manager: ManagedClaudeSessionManagerProtocol
- 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."""
@@ -28,24 +24,45 @@ class MessagingCommandContext(Protocol):
"""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 stop_all_tasks(self) -> int:
+ """Stop every pending or active messaging task."""
...
- async def update_queue_positions(self, tree: MessageTree) -> None:
- """Refresh queued status messages."""
+ async def stop_task(self, scope: MessageScope, node_id: str) -> int:
+ """Stop one pending or active node."""
...
- async def mark_node_processing(self, tree: MessageTree, node_id: str) -> None:
- """Mark a dequeued node as processing."""
+ async def resolve_node_id(
+ self,
+ scope: MessageScope,
+ reference_id: str,
+ ) -> str | None:
+ """Resolve a node or status-message reference."""
...
- async def stop_all_tasks(self) -> int:
- """Stop every pending or active messaging task."""
+ def get_tree_count(self) -> int:
+ """Return the number of conversation trees."""
...
- async def stop_task(self, node_id: str) -> int:
- """Stop one pending or active node."""
+ async def clear_branch(
+ self,
+ scope: MessageScope,
+ node_id: str,
+ ) -> BranchRemovalResult:
+ """Atomically cancel, remove, and persist a conversation branch."""
+ ...
+
+ async def clear_all_state(self, platform: str, chat_id: str) -> frozenset[str]:
+ """Clear all FCC messaging state and return platform message IDs."""
+ ...
+
+ def forget_message_ids(
+ self,
+ platform: str,
+ chat_id: str,
+ message_ids: set[str],
+ ) -> None:
+ """Forget deleted platform message IDs."""
...
def record_outgoing_message(
@@ -58,9 +75,5 @@ class MessagingCommandContext(Protocol):
"""Persist an outgoing platform message ID."""
...
- def update_cancelled_nodes_ui(self, nodes: list[CancelledNode]) -> None:
- """Render cancellation status and persist affected trees."""
- ...
-
__all__ = ["MessagingCommandContext"]
diff --git a/src/free_claude_code/messaging/command_dispatcher.py b/src/free_claude_code/messaging/command_dispatcher.py
index a84d5224..171743ed 100644
--- a/src/free_claude_code/messaging/command_dispatcher.py
+++ b/src/free_claude_code/messaging/command_dispatcher.py
@@ -4,6 +4,12 @@ from .command_context import MessagingCommandContext
from .commands import handle_clear_command, handle_stats_command, handle_stop_command
from .models import IncomingMessage
+_COMMAND_HANDLERS = {
+ "/clear": handle_clear_command,
+ "/stop": handle_stop_command,
+ "/stats": handle_stats_command,
+}
+
def parse_command_base(text: str | None) -> str:
"""Return the slash command without bot mention suffix."""
@@ -23,12 +29,7 @@ async def dispatch_command(
command_base: str,
) -> bool:
"""Dispatch a known command and return whether it was handled."""
- commands = {
- "/clear": handle_clear_command,
- "/stop": handle_stop_command,
- "/stats": handle_stats_command,
- }
- command = commands.get(command_base)
+ command = _COMMAND_HANDLERS.get(command_base)
if command is None:
return False
await command(context, incoming)
diff --git a/src/free_claude_code/messaging/commands.py b/src/free_claude_code/messaging/commands.py
index 7299f466..11f8fc79 100644
--- a/src/free_claude_code/messaging/commands.py
+++ b/src/free_claude_code/messaging/commands.py
@@ -16,8 +16,7 @@ async def handle_stop_command(
# Reply-scoped stop: reply "/stop" to stop only that task.
if incoming.is_reply() and incoming.reply_to_message_id:
reply_id = incoming.reply_to_message_id
- tree = handler.tree_queue.get_tree_for_node(reply_id)
- node_id = handler.tree_queue.resolve_parent_node_id(reply_id) if tree else None
+ node_id = await handler.resolve_node_id(incoming.scope, reply_id)
if not node_id:
msg_id = await handler.outbound.queue_send_message(
@@ -33,7 +32,7 @@ async def handle_stop_command(
)
return
- count = await handler.stop_task(node_id)
+ count = await handler.stop_task(incoming.scope, node_id)
noun = "request" if count == 1 else "requests"
msg_id = await handler.outbound.queue_send_message(
incoming.chat_id,
@@ -66,7 +65,7 @@ async def handle_stats_command(
) -> None:
"""Handle /stats command."""
stats = handler.cli_manager.get_stats()
- tree_count = handler.tree_queue.get_tree_count()
+ tree_count = handler.get_tree_count()
ctx = handler.get_render_ctx()
msg_id = await handler.outbound.queue_send_message(
incoming.chat_id,
@@ -135,50 +134,15 @@ async def _handle_clear_branch(
"""
Clear a branch (replied-to node + all descendants).
- Order: cancel tasks, delete messages, remove branch, update session store.
+ FCC state is removed and persisted before platform deletion begins.
"""
- tree = handler.tree_queue.get_tree_for_node(branch_root_id)
- if not tree:
- return
-
- # 1) Cancel branch tasks (no stop_all)
- cancelled = await handler.tree_queue.cancel_branch(branch_root_id)
- handler.update_cancelled_nodes_ui(cancelled)
-
- # 2) Collect message IDs from branch nodes only
- msg_ids: set[str] = set()
- branch_ids = tree.get_descendants(branch_root_id)
- for nid in branch_ids:
- node = tree.get_node(nid)
- if node:
- if node.incoming.message_id:
- msg_ids.add(str(node.incoming.message_id))
- if node.status_message_id:
- msg_ids.add(str(node.status_message_id))
+ result = await handler.clear_branch(incoming.scope, branch_root_id)
+ msg_ids = set(result.message_ids)
if incoming.message_id:
msg_ids.add(str(incoming.message_id))
- # 3) Delete messages (best-effort)
await _delete_message_ids(handler, incoming.chat_id, msg_ids)
-
- # 4) Remove branch from tree
- _removed, root_id, removed_entire_tree = await handler.tree_queue.remove_branch(
- branch_root_id
- )
-
- # 5) Update session store
- try:
- if removed_entire_tree:
- handler.session_store.remove_tree_snapshot(root_id)
- else:
- updated_tree = handler.tree_queue.get_tree(root_id)
- if updated_tree:
- handler.session_store.save_tree_snapshot(updated_tree.snapshot())
- handler.session_store.forget_message_ids(
- incoming.platform, incoming.chat_id, msg_ids
- )
- except Exception as e:
- logger.warning(f"Failed to update session store after branch clear: {e}")
+ handler.forget_message_ids(incoming.platform, incoming.chat_id, msg_ids)
async def handle_clear_command(
@@ -190,18 +154,13 @@ async def handle_clear_command(
Reply-scoped: reply to a message to clear that branch (node + descendants).
Standalone: global clear (stop all, delete all chat messages, reset store).
"""
- from free_claude_code.messaging.trees import TreeQueueManager
-
if incoming.is_reply() and incoming.reply_to_message_id:
reply_id = incoming.reply_to_message_id
- tree = handler.tree_queue.get_tree_for_node(reply_id)
- branch_root_id = (
- handler.tree_queue.resolve_parent_node_id(reply_id) if tree else None
- )
+ branch_root_id = await handler.resolve_node_id(incoming.scope, reply_id)
if not branch_root_id:
if handler.voice_cancellation is not None:
cancelled = await handler.voice_cancellation.cancel_pending_voice(
- incoming.chat_id, reply_id
+ incoming.scope, reply_id
)
if cancelled is not None:
voice_msg_id, status_msg_id = cancelled
@@ -234,47 +193,10 @@ async def handle_clear_command(
await _handle_clear_branch(handler, incoming, branch_root_id)
return
- # Global clear
- # 1) Stop tasks first (ensures no more work is running).
- await handler.stop_all_tasks()
-
- # 2) Clear chat: best-effort delete messages we can identify.
- msg_ids: set[str] = set()
-
- # Add any recorded message IDs for this chat (commands, command replies, etc).
- try:
- for mid in handler.session_store.get_message_ids_for_chat(
- incoming.platform, incoming.chat_id
- ):
- if mid is not None:
- msg_ids.add(str(mid))
- except Exception as e:
- logger.debug(f"Failed to read message log for /clear: {e}")
-
- try:
- msg_ids.update(
- handler.tree_queue.get_message_ids_for_chat(
- incoming.platform, incoming.chat_id
- )
- )
- except Exception as e:
- logger.warning(f"Failed to gather messages for /clear: {e}")
+ msg_ids = set(await handler.clear_all_state(incoming.platform, incoming.chat_id))
# Also delete the command message itself.
if incoming.message_id is not None:
msg_ids.add(str(incoming.message_id))
await _delete_message_ids(handler, incoming.chat_id, msg_ids)
-
- # 3) Clear persistent state and reset in-memory queue/tree state.
- try:
- handler.session_store.clear_all()
- except Exception as e:
- logger.warning(f"Failed to clear session store: {e}")
-
- handler.replace_tree_queue(
- TreeQueueManager(
- queue_update_callback=handler.update_queue_positions,
- node_started_callback=handler.mark_node_processing,
- )
- )
diff --git a/src/free_claude_code/messaging/models.py b/src/free_claude_code/messaging/models.py
index b63f4f7d..0eb291eb 100644
--- a/src/free_claude_code/messaging/models.py
+++ b/src/free_claude_code/messaging/models.py
@@ -5,6 +5,14 @@ from datetime import UTC, datetime
from typing import Any
+@dataclass(frozen=True, slots=True)
+class MessageScope:
+ """Platform chat namespace in which message IDs are unique."""
+
+ platform: str
+ chat_id: str
+
+
@dataclass
class IncomingMessage:
"""
@@ -28,9 +36,14 @@ class IncomingMessage:
status_message_id: str | None = None
timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
- # Platform-specific raw event for edge cases
+ # Platform-specific raw event stays at ingress and is never persisted by trees.
raw_event: Any = None
def is_reply(self) -> bool:
"""Check if this message is a reply to another message."""
return self.reply_to_message_id is not None
+
+ @property
+ def scope(self) -> MessageScope:
+ """Return the namespace that owns this message's platform IDs."""
+ return MessageScope(platform=str(self.platform), chat_id=str(self.chat_id))
diff --git a/src/free_claude_code/messaging/node_event_pipeline.py b/src/free_claude_code/messaging/node_event_pipeline.py
index 169f187c..8b890af4 100644
--- a/src/free_claude_code/messaging/node_event_pipeline.py
+++ b/src/free_claude_code/messaging/node_event_pipeline.py
@@ -10,21 +10,22 @@ from free_claude_code.core.trace import trace_event
from .cli_event_constants import TRANSCRIPT_EVENT_TYPES, get_status_for_event
from .managed_protocols import ManagedClaudeSessionManagerProtocol
from .safe_diagnostics import text_len_hint
-from .session import SessionStore
from .transcript import TranscriptBuffer
-from .trees import MessageState, MessageTree
+from .trees.transitions import NodeClaim
+
+RecordSession = Callable[[str], Awaitable[None]]
+CompleteClaim = Callable[[str | None], Awaitable[None]]
+FailClaim = Callable[[str, str], Awaitable[None]]
async def handle_session_info_event(
event_data: dict[str, Any],
- tree: MessageTree | None,
- node_id: str,
+ claim: NodeClaim,
captured_session_id: str | None,
temp_session_id: str | None,
*,
cli_manager: ManagedClaudeSessionManagerProtocol,
- session_store: SessionStore,
- save_tree_snapshot: Callable[[MessageTree], None] | None = None,
+ record_session: RecordSession,
) -> tuple[str | None, str | None]:
"""Handle session_info event; return updated (captured_session_id, temp_session_id)."""
if event_data.get("type") != "session_info":
@@ -39,21 +40,12 @@ async def handle_session_info_event(
stage="claude_cli",
event="claude_cli.session.registered",
source="claude_cli",
- node_id=node_id,
+ node_id=claim.node.node_id,
temp_session_id=temp_session_id,
real_session_id=real_session_id,
- tree_root_id=tree.root_id if tree else None,
+ tree_root_id=claim.identity.root_id,
)
- if tree and real_session_id:
- await tree.update_state(
- node_id,
- MessageState.IN_PROGRESS,
- session_id=real_session_id,
- )
- if save_tree_snapshot is None:
- session_store.save_tree_snapshot(tree.snapshot())
- else:
- save_tree_snapshot(tree)
+ await record_session(real_session_id)
return real_session_id, None
@@ -64,14 +56,12 @@ async def process_parsed_cli_event(
update_ui: Callable[..., Awaitable[None]],
last_status: str | None,
had_transcript_events: bool,
- tree: MessageTree | None,
- node_id: str,
+ claim: NodeClaim,
captured_session_id: str | None,
*,
- session_store: SessionStore,
- save_tree_snapshot: Callable[[MessageTree], None] | None = None,
format_status: Callable[..., str],
- propagate_error_to_children: Callable[[str, str, str], Awaitable[None]],
+ complete_claim: CompleteClaim,
+ fail_claim: FailClaim,
log_messaging_error_details: bool = False,
) -> tuple[str | None, bool]:
"""Process a single parsed CLI event. Returns (last_status, had_transcript_events)."""
@@ -96,20 +86,11 @@ async def process_parsed_cli_event(
stage="claude_cli",
event="turn.completed",
source="cli_event",
- node_id=node_id,
+ node_id=claim.node.node_id,
claude_session_id=captured_session_id,
)
await update_ui(format_status("✅", "Complete"), force=True)
- if tree and captured_session_id:
- await tree.update_state(
- node_id,
- MessageState.COMPLETED,
- session_id=captured_session_id,
- )
- if save_tree_snapshot is None:
- session_store.save_tree_snapshot(tree.snapshot())
- else:
- save_tree_snapshot(tree)
+ await complete_claim(captured_session_id)
elif ptype == "error":
error_msg = parsed.get("message", "Unknown error")
em = error_msg if isinstance(error_msg, str) else str(error_msg)
@@ -117,7 +98,7 @@ async def process_parsed_cli_event(
stage="claude_cli",
event="turn.failed",
source="cli_event",
- node_id=node_id,
+ node_id=claim.node.node_id,
claude_session_id=captured_session_id,
cli_error_message=em,
)
@@ -129,7 +110,6 @@ async def process_parsed_cli_event(
text_len_hint(em),
)
await update_ui(format_status("❌", "Error"), force=True)
- if tree:
- await propagate_error_to_children(node_id, error_msg, "Parent task failed")
+ await fail_claim(em, "Parent task failed")
return last_status, had_transcript_events
diff --git a/src/free_claude_code/messaging/node_runner.py b/src/free_claude_code/messaging/node_runner.py
index 6b8eb941..cf2a15a3 100644
--- a/src/free_claude_code/messaging/node_runner.py
+++ b/src/free_claude_code/messaging/node_runner.py
@@ -18,14 +18,9 @@ from .platforms.ports import OutboundMessenger
from .safe_diagnostics import format_exception_for_log
from .session import SessionStore
from .transcript import RenderCtx, TranscriptBuffer
-from .trees import (
- CancellationReason,
- MessageNode,
- MessageState,
- MessageTree,
- TreeQueueManager,
- get_cancel_reason,
-)
+from .trees.manager import TreeQueueManager
+from .trees.snapshot import TreeSnapshot
+from .trees.transitions import CancellationReason, NodeClaim
from .ui_updates import ThrottledTranscriptEditor
@@ -73,68 +68,91 @@ class MessagingNodeRunner:
)
return transcript, self._get_render_ctx()
- def _save_tree(self, tree: MessageTree | None, node_id: str) -> None:
- """Persist tree state after runner-owned mutations."""
- if not tree:
+ def _save_snapshot(self, snapshot: TreeSnapshot | None) -> None:
+ """Persist a snapshot returned by the active aggregate manager."""
+ if snapshot is None:
return
- active_tree = self._get_tree_queue().get_tree_for_node(node_id)
- if active_tree is not tree:
- logger.debug(
- "Skipping stale tree save for node {} after cancellation/clear",
- node_id,
- )
+ self.session_store.save_tree_snapshot(snapshot)
+
+ async def _record_session(self, claim: NodeClaim, session_id: str) -> None:
+ snapshot = await self._get_tree_queue().record_session(claim, session_id)
+ self._save_snapshot(snapshot)
+
+ async def _complete_claim(
+ self,
+ claim: NodeClaim,
+ session_id: str | None,
+ ) -> None:
+ snapshot = await self._get_tree_queue().complete_claim(claim, session_id)
+ self._save_snapshot(snapshot)
+
+ async def _fail_claim(
+ self,
+ claim: NodeClaim,
+ *,
+ propagate: bool,
+ child_status_text: str | None = None,
+ ) -> None:
+ result = await self._get_tree_queue().fail_claim(
+ claim,
+ propagate=propagate,
+ )
+ self._save_snapshot(result.snapshot)
+ if child_status_text is None:
return
- self.session_store.save_tree_snapshot(tree.snapshot())
+ for child in result.affected:
+ if child.node_id == claim.node.node_id:
+ continue
+ self.outbound.fire_and_forget(
+ self.outbound.queue_edit_message(
+ child.scope.chat_id,
+ child.status_message_id,
+ self._format_status("❌", "Cancelled:", child_status_text),
+ parse_mode=self._get_parse_mode(),
+ )
+ )
async def process_node(
self,
- node_id: str,
- node: MessageNode,
+ claim: NodeClaim,
) -> None:
"""Core task processor for a single CLI interaction."""
- incoming = node.incoming
- status_msg_id = node.status_message_id
- chat_id = incoming.chat_id
+ node_id = claim.node.node_id
+ status_msg_id = claim.node.status_message_id
+ chat_id = claim.node.scope.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)
+ await self._process_node_impl(claim, chat_id, status_msg_id)
async def _process_node_impl(
self,
- node_id: str,
- node: MessageNode,
+ claim: NodeClaim,
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)
+ node_id = claim.node.node_id
transcript, render_ctx = self._create_transcript_and_render_ctx()
had_transcript_events = False
- had_non_exit_error = False
+ non_exit_error: str | None = None
+ terminal_seen = False
captured_session_id = None
temp_session_id = None
last_status: str | None = None
- parent_session_id = None
+ parent_session_id = claim.parent_session_id
platform_nm = self.platform_name
- 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,
- )
+ 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(
outbound=self.outbound,
@@ -188,7 +206,7 @@ class MessagingNodeRunner:
source=platform_nm,
chat_id=chat_id,
node_id=node_id,
- prompt=incoming.text,
+ prompt=claim.prompt,
fork_session_arg=bool(parent_session_id),
resume_session_arg=parent_session_id,
)
@@ -199,13 +217,10 @@ class MessagingNodeRunner:
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, node_id)
+ await self._fail_claim(
+ claim,
+ propagate=False,
+ )
trace_event(
stage="claude_cli",
event="claude_cli.session.limit_reached",
@@ -216,7 +231,7 @@ class MessagingNodeRunner:
return
async for event_data in cli_session.start_task(
- incoming.text,
+ claim.prompt,
session_id=parent_session_id,
fork_session=bool(parent_session_id),
):
@@ -231,14 +246,12 @@ class MessagingNodeRunner:
temp_session_id,
) = await handle_session_info_event(
event_data,
- tree,
- node_id,
+ claim,
captured_session_id,
temp_session_id,
cli_manager=self.cli_manager,
- session_store=self.session_store,
- save_tree_snapshot=lambda updated_tree: self._save_tree(
- updated_tree, node_id
+ record_session=lambda session_id: self._record_session(
+ claim, session_id
),
)
if event_data.get("type") == "session_info":
@@ -253,10 +266,29 @@ class MessagingNodeRunner:
if (
ptype == "error"
and parsed.get("source") == "exit"
- and had_non_exit_error
+ and non_exit_error is not None
):
+ await self._fail_claim(
+ claim,
+ propagate=True,
+ child_status_text="Parent task failed",
+ )
+ terminal_seen = True
continue
+ propagate_failure = parsed.get("source") == "exit"
+
+ async def fail_parsed_event(
+ error_message: str,
+ child_status: str,
+ propagate: bool = propagate_failure,
+ ) -> None:
+ await self._fail_claim(
+ claim,
+ propagate=propagate,
+ child_status_text=child_status,
+ )
+
(
last_status,
had_transcript_events,
@@ -266,21 +298,47 @@ class MessagingNodeRunner:
update_ui,
last_status,
had_transcript_events,
- tree,
- node_id,
+ claim,
captured_session_id,
- session_store=self.session_store,
- save_tree_snapshot=lambda updated_tree: self._save_tree(
- updated_tree, node_id
- ),
format_status=self._format_status,
- propagate_error_to_children=self.propagate_error_to_children,
+ complete_claim=lambda session_id: self._complete_claim(
+ claim, session_id
+ ),
+ fail_claim=fail_parsed_event,
log_messaging_error_details=self._log_messaging_error_details,
)
if ptype == "error" and parsed.get("source") != "exit":
- had_non_exit_error = True
+ error_message = parsed.get("message", "Unknown error")
+ non_exit_error = (
+ error_message
+ if isinstance(error_message, str)
+ else str(error_message)
+ )
+ if (ptype == "error" and parsed.get("source") == "exit") or (
+ ptype == "complete" and parsed.get("status") == "success"
+ ):
+ terminal_seen = True
+
+ if non_exit_error is not None and not terminal_seen:
+ await self._fail_claim(
+ claim,
+ propagate=True,
+ child_status_text="Parent task failed",
+ )
+ elif not terminal_seen:
+ error_message = "Claude CLI ended without a terminal event"
+ transcript.apply({"type": "error", "message": error_message})
+ await update_ui(
+ self._format_status("💥", "Task Failed", None),
+ force=True,
+ )
+ await self._fail_claim(
+ claim,
+ propagate=True,
+ child_status_text="Parent task failed",
+ )
- except asyncio.CancelledError:
+ except asyncio.CancelledError as exc:
trace_event(
stage="claude_cli",
event="turn.processor.cancelled",
@@ -289,7 +347,7 @@ class MessagingNodeRunner:
node_id=node_id,
)
logger.warning(f"HANDLER: Task cancelled for node {node_id}")
- if get_cancel_reason(node) is CancellationReason.STOP:
+ if exc.args and exc.args[0] is CancellationReason.STOP:
await update_ui(self._format_status("⏹", "Stopped.", None), force=True)
else:
transcript.apply({"type": "error", "message": "Task was cancelled"})
@@ -297,11 +355,10 @@ class MessagingNodeRunner:
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, node_id)
+ await self._fail_claim(
+ claim,
+ propagate=False,
+ )
except Exception as e:
trace_event(
stage="claude_cli",
@@ -320,10 +377,11 @@ class MessagingNodeRunner:
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"
- )
+ await self._fail_claim(
+ claim,
+ propagate=True,
+ child_status_text="Parent task failed",
+ )
finally:
trace_event(
stage="routing",
@@ -347,28 +405,5 @@ class MessagingNodeRunner:
),
)
- 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), node_id)
- for child in affected[1:]:
- self.outbound.fire_and_forget(
- self.outbound.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/src/free_claude_code/messaging/platforms/discord.py b/src/free_claude_code/messaging/platforms/discord.py
index f6cb6793..ca005153 100644
--- a/src/free_claude_code/messaging/platforms/discord.py
+++ b/src/free_claude_code/messaging/platforms/discord.py
@@ -10,7 +10,7 @@ from loguru import logger
from free_claude_code.core.diagnostics import format_user_error_preview
from ..limiter import MessagingRateLimiter
-from ..models import IncomingMessage
+from ..models import IncomingMessage, MessageScope
from ..rendering.discord_markdown import format_status_discord
from ..voice import Transcriber
from .discord_inbound import (
@@ -139,10 +139,10 @@ class DiscordRuntime:
logger.info("Discord platform connected")
async def cancel_pending_voice(
- self, chat_id: str, reply_id: str
+ self, scope: MessageScope, reply_id: str
) -> tuple[str, str] | None:
"""Cancel a pending voice transcription."""
- return await self._voice_flow.cancel_pending_voice(chat_id, reply_id)
+ return await self._voice_flow.cancel_pending_voice(scope, reply_id)
async def _handle_voice_note(
self, message: Any, attachment: Any, channel_id: str
diff --git a/src/free_claude_code/messaging/platforms/ports.py b/src/free_claude_code/messaging/platforms/ports.py
index ba847b70..be4edb04 100644
--- a/src/free_claude_code/messaging/platforms/ports.py
+++ b/src/free_claude_code/messaging/platforms/ports.py
@@ -4,7 +4,7 @@ from collections.abc import Awaitable, Callable
from dataclasses import dataclass
from typing import Any, Protocol, runtime_checkable
-from ..models import IncomingMessage
+from ..models import IncomingMessage, MessageScope
InboundMessageHandler = Callable[[IncomingMessage], Awaitable[None]]
@@ -66,7 +66,7 @@ class VoiceCancellation(Protocol):
"""Optional voice-note cancellation port used by /clear replies."""
async def cancel_pending_voice(
- self, chat_id: str, reply_id: str
+ self, scope: MessageScope, reply_id: str
) -> tuple[str, str] | None: ...
diff --git a/src/free_claude_code/messaging/platforms/telegram.py b/src/free_claude_code/messaging/platforms/telegram.py
index 342e23e8..b1f910d4 100644
--- a/src/free_claude_code/messaging/platforms/telegram.py
+++ b/src/free_claude_code/messaging/platforms/telegram.py
@@ -13,7 +13,7 @@ from loguru import logger
from free_claude_code.core.diagnostics import format_user_error_preview
from ..limiter import MessagingRateLimiter
-from ..models import IncomingMessage
+from ..models import IncomingMessage, MessageScope
from ..rendering.telegram_markdown import escape_md_v2
from ..voice import Transcriber
from .ports import InboundMessageHandler
@@ -84,10 +84,10 @@ class TelegramRuntime:
self._log_api_error_tracebacks = log_api_error_tracebacks
async def cancel_pending_voice(
- self, chat_id: str, reply_id: str
+ self, scope: MessageScope, reply_id: str
) -> tuple[str, str] | None:
"""Cancel a pending voice transcription."""
- return await self._voice_flow.cancel_pending_voice(chat_id, reply_id)
+ return await self._voice_flow.cancel_pending_voice(scope, reply_id)
async def start(self) -> None:
"""Initialize and connect to Telegram."""
diff --git a/src/free_claude_code/messaging/platforms/voice_flow.py b/src/free_claude_code/messaging/platforms/voice_flow.py
index 907df9cb..96fb3a7f 100644
--- a/src/free_claude_code/messaging/platforms/voice_flow.py
+++ b/src/free_claude_code/messaging/platforms/voice_flow.py
@@ -12,7 +12,7 @@ from loguru import logger
from free_claude_code.core.diagnostics import format_user_error_preview
-from ..models import IncomingMessage
+from ..models import IncomingMessage, MessageScope
from ..voice import PendingVoiceRegistry, Transcriber
AUDIO_EXTENSIONS = (".ogg", ".mp4", ".mp3", ".wav", ".m4a")
@@ -46,6 +46,10 @@ class VoiceNoteRequest:
message_thread_id: str | None = None
username: str | None = None
+ @property
+ def scope(self) -> MessageScope:
+ return MessageScope(platform=self.platform, chat_id=self.chat_id)
+
def is_audio_metadata(filename: str | None, content_type: str | None) -> bool:
"""Return whether attachment metadata describes an audio file."""
@@ -113,26 +117,28 @@ class VoiceNoteFlow:
return True
async def register_pending_voice(
- self, chat_id: str, voice_msg_id: str, status_msg_id: str
+ self, scope: MessageScope, voice_msg_id: str, status_msg_id: str
) -> None:
"""Register a voice note as pending transcription."""
- await self._pending_voice.register(chat_id, voice_msg_id, status_msg_id)
+ await self._pending_voice.register(scope, voice_msg_id, status_msg_id)
async def cancel_pending_voice(
- self, chat_id: str, reply_id: str
+ self, scope: MessageScope, reply_id: str
) -> tuple[str, str] | None:
"""Cancel a pending voice transcription."""
- return await self._pending_voice.cancel(chat_id, reply_id)
+ return await self._pending_voice.cancel(scope, reply_id)
- async def is_voice_still_pending(self, chat_id: str, voice_msg_id: str) -> bool:
+ async def is_voice_still_pending(
+ self, scope: MessageScope, voice_msg_id: str
+ ) -> bool:
"""Return whether a voice note is still pending."""
- return await self._pending_voice.is_pending(chat_id, voice_msg_id)
+ return await self._pending_voice.is_pending(scope, voice_msg_id)
async def complete_pending_voice(
- self, chat_id: str, voice_msg_id: str, status_msg_id: str
+ self, scope: MessageScope, voice_msg_id: str, status_msg_id: str
) -> None:
"""Mark a voice note as no longer pending."""
- await self._pending_voice.complete(chat_id, voice_msg_id, status_msg_id)
+ await self._pending_voice.complete(scope, voice_msg_id, status_msg_id)
async def handle(
self,
@@ -159,7 +165,7 @@ class VoiceNoteFlow:
)
status_msg_id_text = str(status_msg_id)
await self.register_pending_voice(
- request.chat_id,
+ request.scope,
request.message_id,
status_msg_id_text,
)
@@ -180,14 +186,14 @@ class VoiceNoteFlow:
transcribed = await transcriber.transcribe(tmp_path)
if not await self.is_voice_still_pending(
- request.chat_id,
+ request.scope,
request.message_id,
):
await queue_delete_messages(request.chat_id, [status_msg_id_text])
return True
await self.complete_pending_voice(
- request.chat_id,
+ request.scope,
request.message_id,
status_msg_id_text,
)
@@ -264,7 +270,7 @@ class VoiceNoteFlow:
handed_off: bool,
) -> None:
await self.complete_pending_voice(
- request.chat_id,
+ request.scope,
request.message_id,
status_msg_id,
)
diff --git a/src/free_claude_code/messaging/session/persistence.py b/src/free_claude_code/messaging/session/persistence.py
index 5154734f..066be970 100644
--- a/src/free_claude_code/messaging/session/persistence.py
+++ b/src/free_claude_code/messaging/session/persistence.py
@@ -35,6 +35,7 @@ class DebouncedJsonPersistence:
self._debounce_secs = debounce_secs
self._save_timer: threading.Timer | None = None
self._timer_lock = threading.Lock()
+ self._writer_lock = threading.Lock()
self._save_generation = 0
def load_json(self) -> dict[str, Any]:
@@ -74,12 +75,22 @@ class DebouncedJsonPersistence:
def _write_pending(self, pending: _PendingWrite) -> None:
try:
- self.write_data(pending.snapshot)
+ written = self._write_if_current(pending)
except Exception as e:
logger.error("Failed to save sessions: {}", e)
self._on_dirty(True)
return
- self._mark_clean_if_current(pending.generation)
+ if written:
+ self._mark_clean_if_current(pending.generation)
+
+ def _write_if_current(self, pending: _PendingWrite) -> bool:
+ """Serialize writers and reject a snapshot superseded before replace."""
+ with self._writer_lock:
+ with self._timer_lock:
+ if pending.generation != self._save_generation:
+ return False
+ self._write_file(pending.snapshot)
+ return True
def _snapshot_for_write(
self, *, expected_generation: int | None = None
@@ -110,6 +121,19 @@ class DebouncedJsonPersistence:
self._on_dirty(False)
def write_data(self, data: dict[str, Any]) -> None:
+ """Write authoritative state after invalidating older pending snapshots."""
+ with self._timer_lock:
+ if self._save_timer is not None:
+ self._save_timer.cancel()
+ self._save_timer = None
+ self._save_generation += 1
+ pending = _PendingWrite(
+ generation=self._save_generation,
+ snapshot=data,
+ )
+ self._write_pending(pending)
+
+ def _write_file(self, data: dict[str, Any]) -> None:
abs_target = os.path.abspath(self.storage_path)
dir_name = os.path.dirname(abs_target) or "."
fd, tmp_path = tempfile.mkstemp(
diff --git a/src/free_claude_code/messaging/session/store.py b/src/free_claude_code/messaging/session/store.py
index a194b9f1..a6d22e99 100644
--- a/src/free_claude_code/messaging/session/store.py
+++ b/src/free_claude_code/messaging/session/store.py
@@ -1,10 +1,15 @@
"""Persistent messaging conversation state store."""
import threading
+from copy import deepcopy
from loguru import logger
-from free_claude_code.messaging.trees import ConversationSnapshot, TreeSnapshot
+from free_claude_code.messaging.trees import (
+ ConversationSnapshot,
+ TreeIdentity,
+ TreeSnapshot,
+)
from .message_log import MessageLog
from .persistence import DebouncedJsonPersistence
@@ -81,26 +86,22 @@ class SessionStore:
def load_conversation_snapshot(self) -> ConversationSnapshot:
with self._lock:
- return ConversationSnapshot(trees=dict(self._conversation.trees))
+ return deepcopy(self._conversation)
def save_conversation_snapshot(self, snapshot: ConversationSnapshot) -> None:
with self._lock:
- self._conversation = snapshot
+ self._conversation = deepcopy(snapshot)
self._persistence.schedule_save()
def save_tree_snapshot(self, snapshot: TreeSnapshot) -> None:
with self._lock:
- self._conversation = self._conversation.with_tree(snapshot)
+ self._conversation = self._conversation.with_tree(deepcopy(snapshot))
self._persistence.schedule_save()
logger.debug("Saved tree {}", snapshot.root_id)
- def get_tree_snapshot(self, root_id: str) -> TreeSnapshot | None:
+ def remove_tree_snapshot(self, identity: TreeIdentity) -> None:
with self._lock:
- return self._conversation.trees.get(root_id)
-
- def remove_tree_snapshot(self, root_id: str) -> None:
- with self._lock:
- self._conversation = self._conversation.without_tree(root_id)
+ self._conversation = self._conversation.without_tree(identity)
self._persistence.schedule_save()
def flush_pending_save(self) -> None:
@@ -149,10 +150,14 @@ class SessionStore:
with self._lock:
self._conversation = ConversationSnapshot()
self._message_log.clear()
- snapshot = self._snapshot_for_persistence()
- self._set_dirty(False)
- try:
- self._persistence.write_data(snapshot)
- except Exception as e:
- logger.error("Failed to save sessions: {}", e)
- self._set_dirty(True)
+ self._write_current_state()
+
+ def clear_conversation_snapshot(self) -> None:
+ """Authoritatively clear trees while preserving newer message logs."""
+ with self._lock:
+ self._conversation = ConversationSnapshot()
+ self._write_current_state()
+
+ def _write_current_state(self) -> None:
+ self._set_dirty(False)
+ self._persistence.write_data(self._snapshot_for_persistence())
diff --git a/src/free_claude_code/messaging/trees/__init__.py b/src/free_claude_code/messaging/trees/__init__.py
index aa993b7b..f911769f 100644
--- a/src/free_claude_code/messaging/trees/__init__.py
+++ b/src/free_claude_code/messaging/trees/__init__.py
@@ -1,31 +1,38 @@
-"""Message tree data structures and queue management."""
+"""Internal messaging tree package facade."""
-from .cancellation import (
+from .identity import TreeIdentity
+from .manager import TreeQueueManager
+from .node import MessageState
+from .snapshot import ConversationSnapshot, TreeSnapshot
+from .transitions import (
+ BranchRemovalResult,
CancellationReason,
+ CancellationResult,
CancellationUiOwner,
- CancelledNode,
- get_cancel_reason,
- set_cancel_reason,
+ FailureResult,
+ NodeClaim,
+ NodeUiTarget,
+ NodeView,
+ QueueDecision,
+ QueueEntry,
+ ReplyTarget,
)
-from .manager import TreeQueueManager
-from .node import MessageNode, MessageState
-from .processor import TreeQueueProcessor
-from .repository import TreeRepository
-from .runtime import MessageTree
-from .snapshot import ConversationSnapshot, TreeSnapshot
__all__ = [
+ "BranchRemovalResult",
"CancellationReason",
+ "CancellationResult",
"CancellationUiOwner",
- "CancelledNode",
"ConversationSnapshot",
- "MessageNode",
+ "FailureResult",
"MessageState",
- "MessageTree",
+ "NodeClaim",
+ "NodeUiTarget",
+ "NodeView",
+ "QueueDecision",
+ "QueueEntry",
+ "ReplyTarget",
+ "TreeIdentity",
"TreeQueueManager",
- "TreeQueueProcessor",
- "TreeRepository",
"TreeSnapshot",
- "get_cancel_reason",
- "set_cancel_reason",
]
diff --git a/src/free_claude_code/messaging/trees/cancellation.py b/src/free_claude_code/messaging/trees/cancellation.py
deleted file mode 100644
index f31032f2..00000000
--- a/src/free_claude_code/messaging/trees/cancellation.py
+++ /dev/null
@@ -1,52 +0,0 @@
-"""Typed cancellation facts for messaging tree UI ownership."""
-
-from dataclasses import dataclass
-from enum import Enum
-
-from .node import MessageNode
-
-_CANCEL_REASON_CONTEXT_KEY = "cancel_reason"
-
-
-class CancellationUiOwner(Enum):
- """Who owns the final user-visible cancellation edit for a node."""
-
- RUNNER = "runner"
- WORKFLOW = "workflow"
-
-
-class CancellationReason(Enum):
- """Why a node was cancelled, when the runner needs UI-specific cleanup."""
-
- STOP = "stop"
-
-
-@dataclass(frozen=True)
-class CancelledNode:
- """A cancelled node plus the component responsible for its final UI edit."""
-
- node: MessageNode
- ui_owner: CancellationUiOwner
-
-
-def set_cancel_reason(node: MessageNode, reason: CancellationReason | None) -> None:
- """Attach or remove cancellation reason without clobbering other context."""
- context = dict(node.context) if isinstance(node.context, dict) else {}
- if reason is None:
- context.pop(_CANCEL_REASON_CONTEXT_KEY, None)
- else:
- context[_CANCEL_REASON_CONTEXT_KEY] = reason.value
- node.set_context(context or None)
-
-
-def get_cancel_reason(node: MessageNode) -> CancellationReason | None:
- """Return a typed cancellation reason from node context."""
- if not isinstance(node.context, dict):
- return None
- raw_reason = node.context.get(_CANCEL_REASON_CONTEXT_KEY)
- if not isinstance(raw_reason, str):
- return None
- try:
- return CancellationReason(raw_reason)
- except ValueError:
- return None
diff --git a/src/free_claude_code/messaging/trees/graph.py b/src/free_claude_code/messaging/trees/graph.py
index df4cc249..008a455a 100644
--- a/src/free_claude_code/messaging/trees/graph.py
+++ b/src/free_claude_code/messaging/trees/graph.py
@@ -2,9 +2,15 @@
from loguru import logger
-from ..models import IncomingMessage
+from ..models import MessageScope
+from .identity import TreeIdentity
from .node import MessageNode, MessageState
-from .snapshot import TreeSnapshot, node_from_snapshot, node_to_snapshot
+from .snapshot import (
+ TreeSnapshot,
+ node_from_snapshot,
+ node_scope_from_snapshot,
+ node_to_snapshot,
+)
class MessageTreeGraph:
@@ -12,6 +18,10 @@ class MessageTreeGraph:
def __init__(self, root_node: MessageNode) -> None:
self.root_id = root_node.node_id
+ self.identity = TreeIdentity(
+ scope=root_node.scope,
+ root_id=root_node.node_id,
+ )
self._nodes: dict[str, MessageNode] = {root_node.node_id: root_node}
self._status_to_node: dict[str, str] = {
root_node.status_message_id: root_node.node_id
@@ -21,16 +31,32 @@ class MessageTreeGraph:
self,
*,
node_id: str,
- incoming: IncomingMessage,
+ scope: MessageScope,
+ prompt: str,
status_message_id: str,
parent_id: str,
) -> MessageNode:
+ if scope != self.identity.scope:
+ raise ValueError("A reply cannot cross platform chat boundaries")
if parent_id not in self._nodes:
raise ValueError(f"Parent node {parent_id} not found in tree")
+ if node_id in self._nodes:
+ raise ValueError(f"Node {node_id} already exists in tree")
+ if node_id in self._status_to_node:
+ raise ValueError(f"Message reference {node_id} already exists in tree")
+ if status_message_id in self._status_to_node:
+ raise ValueError(
+ f"Status message {status_message_id} already exists in tree"
+ )
+ if status_message_id in self._nodes:
+ raise ValueError(
+ f"Message reference {status_message_id} already exists in tree"
+ )
node = MessageNode(
node_id=node_id,
- incoming=incoming,
+ scope=scope,
+ prompt=prompt,
status_message_id=status_message_id,
parent_id=parent_id,
state=MessageState.PENDING,
@@ -47,12 +73,6 @@ class MessageTreeGraph:
def get_root(self) -> MessageNode:
return self._nodes[self.root_id]
- def get_children(self, node_id: str) -> list[MessageNode]:
- node = self._nodes.get(node_id)
- if not node:
- return []
- return [self._nodes[cid] for cid in node.children_ids if cid in self._nodes]
-
def get_parent(self, node_id: str) -> MessageNode | None:
node = self._nodes.get(node_id)
if not node or not node.parent_id:
@@ -63,29 +83,6 @@ class MessageTreeGraph:
parent = self.get_parent(node_id)
return parent.session_id if parent else None
- def update_node_state(
- self,
- node_id: str,
- state: MessageState,
- *,
- session_id: str | None = None,
- error_message: str | None = None,
- ) -> bool:
- node = self._nodes.get(node_id)
- if not node:
- logger.warning("Node {} not found for state update", node_id)
- return False
- node.update_state(
- state,
- session_id=session_id,
- error_message=error_message,
- )
- logger.debug("Node {} state -> {}", node_id, state.value)
- return True
-
- def has_node(self, node_id: str) -> bool:
- return node_id in self._nodes
-
def find_node_by_status_message(self, status_msg_id: str) -> MessageNode | None:
node_id = self._status_to_node.get(status_msg_id)
return self._nodes.get(node_id) if node_id else None
@@ -106,17 +103,17 @@ class MessageTreeGraph:
stack.extend(node.children_ids)
return result
- def remove_branch(self, branch_root_id: str) -> list[MessageNode]:
+ def remove_branch(self, branch_root_id: str) -> None:
if branch_root_id not in self._nodes:
- return []
+ return
parent = self.get_parent(branch_root_id)
- removed: list[MessageNode] = []
+ removed_count = 0
for node_id in self.get_descendants(branch_root_id):
node = self._nodes.get(node_id)
if not node:
continue
- removed.append(node)
+ removed_count += 1
del self._nodes[node_id]
self._status_to_node.pop(node.status_message_id, None)
@@ -127,11 +124,11 @@ class MessageTreeGraph:
if child_id != branch_root_id
]
- logger.debug("Removed branch {} ({} nodes)", branch_root_id, len(removed))
- return removed
+ logger.debug("Removed branch {} ({} nodes)", branch_root_id, removed_count)
def snapshot(self) -> TreeSnapshot:
return TreeSnapshot(
+ scope=self.identity.scope,
root_id=self.root_id,
nodes={
node_id: node_to_snapshot(node) for node_id, node in self._nodes.items()
@@ -141,14 +138,48 @@ class MessageTreeGraph:
@classmethod
def from_snapshot(cls, snapshot: TreeSnapshot) -> MessageTreeGraph:
root_data = snapshot.nodes[snapshot.root_id]
- root_node = node_from_snapshot(root_data)
+ if not isinstance(root_data, dict):
+ raise ValueError("Tree snapshot contains an invalid root node")
+ if node_scope_from_snapshot(root_data) not in (None, snapshot.scope):
+ raise ValueError("Tree snapshot contains a cross-scope node")
+ root_node = node_from_snapshot(root_data, snapshot.scope)
+ if root_node.node_id != snapshot.root_id:
+ raise ValueError("Tree snapshot root key does not match its node ID")
graph = cls(root_node)
- for node_id, node_data in snapshot.nodes.items():
- if node_id == snapshot.root_id:
+ reference_owner = {
+ root_node.node_id: root_node.node_id,
+ root_node.status_message_id: root_node.node_id,
+ }
+ for snapshot_node_id, node_data in snapshot.nodes.items():
+ if snapshot_node_id == snapshot.root_id:
continue
if not isinstance(node_data, dict):
- continue
- node = node_from_snapshot(node_data)
+ raise ValueError("Tree snapshot contains an invalid node")
+ if node_scope_from_snapshot(node_data) not in (None, snapshot.scope):
+ raise ValueError("Tree snapshot contains a cross-scope node")
+ node = node_from_snapshot(node_data, snapshot.scope)
+ if str(snapshot_node_id) != node.node_id:
+ raise ValueError("Tree snapshot node key does not match its node ID")
+ if node.node_id in graph._nodes:
+ raise ValueError(f"Duplicate node {node.node_id} in tree snapshot")
+ for reference in {node.node_id, node.status_message_id}:
+ owner = reference_owner.get(reference)
+ if owner is not None and owner != node.node_id:
+ raise ValueError(
+ f"Duplicate message reference {reference} in tree snapshot"
+ )
+ reference_owner[reference] = node.node_id
graph._nodes[node.node_id] = node
graph._status_to_node[node.status_message_id] = node.node_id
+
+ if root_node.parent_id is not None:
+ raise ValueError("Tree snapshot root cannot have a parent")
+ for node in graph._nodes.values():
+ if node.node_id == graph.root_id:
+ continue
+ if node.parent_id is None or node.parent_id not in graph._nodes:
+ raise ValueError(f"Node {node.node_id} has no valid parent")
+ graph._nodes[node.parent_id].children_ids.append(node.node_id)
+ if set(graph.get_descendants(graph.root_id)) != set(graph._nodes):
+ raise ValueError("Tree snapshot contains a disconnected branch")
return graph
diff --git a/src/free_claude_code/messaging/trees/identity.py b/src/free_claude_code/messaging/trees/identity.py
new file mode 100644
index 00000000..ada6bb3b
--- /dev/null
+++ b/src/free_claude_code/messaging/trees/identity.py
@@ -0,0 +1,16 @@
+"""Stable and runtime identities for messaging conversation trees."""
+
+from dataclasses import dataclass
+
+from ..models import MessageScope
+
+
+@dataclass(frozen=True, slots=True)
+class TreeIdentity:
+ """Customer conversation identity, independent of one runtime generation."""
+
+ scope: MessageScope
+ root_id: str
+
+
+__all__ = ["TreeIdentity"]
diff --git a/src/free_claude_code/messaging/trees/manager.py b/src/free_claude_code/messaging/trees/manager.py
index 0951b6a6..ba6afd61 100644
--- a/src/free_claude_code/messaging/trees/manager.py
+++ b/src/free_claude_code/messaging/trees/manager.py
@@ -1,31 +1,61 @@
-"""Public manager API for tree-based messaging queues."""
+"""Public facade for atomic messaging tree aggregates."""
import asyncio
-from collections.abc import Awaitable, Callable
+from collections.abc import Callable, Coroutine
+from typing import Any
from loguru import logger
-from ..models import IncomingMessage
-from .cancellation import (
- CancellationReason,
- CancellationUiOwner,
- CancelledNode,
- set_cancel_reason,
-)
+from ..models import IncomingMessage, MessageScope
+from .identity import TreeIdentity
from .node import MessageNode, MessageState
-from .processor import TreeQueueProcessor
+from .processor import (
+ CancelledTask,
+ NodeProcessor,
+ NodeStartedCallback,
+ QueueUpdateCallback,
+ TreeQueueProcessor,
+)
from .repository import TreeRepository
from .runtime import MessageTree
-from .snapshot import ConversationSnapshot
+from .snapshot import ConversationSnapshot, TreeSnapshot
+from .transitions import (
+ BranchRemovalResult,
+ CancellationEffect,
+ CancellationReason,
+ CancellationResult,
+ CancellationUiOwner,
+ FailureResult,
+ NodeClaim,
+ NodeUiTarget,
+ NodeView,
+ QueueDecision,
+ ReplyTarget,
+ TreeCancellation,
+)
CANCEL_TASK_DRAIN_TIMEOUT_S = 5.0
-async def _drain_cancelled_tasks(tasks: list[asyncio.Task]) -> None:
- """Wait briefly for cancelled node tasks to finish their cleanup."""
+async def _finish_transition[T](awaitable: Coroutine[Any, Any, T]) -> T:
+ """Deliver a transition result even if its caller is cancelled mid-commit."""
+ task = asyncio.create_task(awaitable)
+ current = asyncio.current_task()
+ while True:
+ try:
+ return await asyncio.shield(task)
+ except asyncio.CancelledError:
+ if task.done():
+ return task.result()
+ if current is not None:
+ while current.cancelling():
+ current.uncancel()
+
+
+async def _drain_cancelled_tasks(tasks: list[asyncio.Task[None]]) -> None:
+ """Wait briefly for cancelled claims to finish aggregate cleanup."""
if not tasks:
return
-
done, pending = await asyncio.wait(
set(tasks),
timeout=CANCEL_TASK_DRAIN_TIMEOUT_S,
@@ -35,7 +65,6 @@ async def _drain_cancelled_tasks(tasks: list[asyncio.Task]) -> None:
"Timed out waiting for {} cancelled messaging task(s) to finish cleanup",
len(pending),
)
-
for task in done:
if task.cancelled():
continue
@@ -43,468 +72,489 @@ async def _drain_cancelled_tasks(tasks: list[asyncio.Task]) -> None:
task.result()
except Exception as exc:
logger.debug(
- "Cancelled messaging task finished with {}",
- type(exc).__name__,
+ "Cancelled messaging task finished with {}", type(exc).__name__
)
class TreeQueueManager:
- """
- Manages multiple message trees: index + async processing.
-
- Each new conversation creates a new tree.
- Replies to existing messages add nodes to existing trees.
- """
+ """Locate aggregates and coordinate tasks without exposing mutable trees."""
def __init__(
self,
- queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None = None,
- node_started_callback: Callable[[MessageTree, str], Awaitable[None]]
- | None = None,
+ node_processor: NodeProcessor,
+ *,
+ queue_update_callback: QueueUpdateCallback | None = None,
+ node_started_callback: NodeStartedCallback | None = None,
+ unexpected_failure_callback: Callable[[FailureResult], None] | None = None,
_repository: TreeRepository | None = None,
+ _restored_snapshot: ConversationSnapshot | None = None,
+ _restored_stale_targets: tuple[NodeUiTarget, ...] = (),
) -> None:
self._repository = _repository or TreeRepository()
+ self._lock = asyncio.Lock()
self._processor = TreeQueueProcessor(
+ node_processor,
+ claim_failure_callback=self._handle_processor_failure,
+ claim_finished_callback=self._finish_claim,
queue_update_callback=queue_update_callback,
node_started_callback=node_started_callback,
)
- self._lock = asyncio.Lock()
-
+ self._restored_snapshot = _restored_snapshot
+ self._restored_stale_targets = _restored_stale_targets
+ self._unexpected_failure_callback = unexpected_failure_callback
logger.info("TreeQueueManager initialized")
- async def create_tree(
+ @property
+ def restored_snapshot(self) -> ConversationSnapshot | None:
+ return self._restored_snapshot
+
+ @property
+ def restored_stale_targets(self) -> tuple[NodeUiTarget, ...]:
+ return self._restored_stale_targets
+
+ async def admit(
self,
- node_id: str,
incoming: IncomingMessage,
status_message_id: str,
- ) -> MessageTree:
- """
- Create a new tree with a root node.
-
- Args:
- node_id: ID for the root node
- incoming: The incoming message
- status_message_id: Bot's status message ID
-
- Returns:
- The created MessageTree
- """
+ *,
+ parent_node_id: str | None = None,
+ ) -> QueueDecision:
+ """Publish one admission before its processor can begin."""
+ node_id = str(incoming.message_id)
+ scope = incoming.scope
+ prompt = incoming.text or ""
async with self._lock:
- root_node = MessageNode(
- node_id=node_id,
- incoming=incoming,
- status_message_id=status_message_id,
- state=MessageState.PENDING,
- )
+ duplicate_tree = self._repository.get_tree_for_reference(scope, node_id)
+ if duplicate_tree is None:
+ duplicate_tree = self._repository.get_tree_for_reference(
+ scope,
+ status_message_id,
+ )
+ if duplicate_tree is not None:
+ return await duplicate_tree.enqueue_or_claim(node_id)
+
+ tree: MessageTree | None = None
+ resolved_parent: ReplyTarget | None = None
+ if parent_node_id is not None:
+ tree = self._repository.get_tree_for_reference(scope, parent_node_id)
+ if tree is not None:
+ resolved_parent = await tree.resolve_reply(parent_node_id)
+
+ if tree is not None and resolved_parent is not None:
+ decision = await tree.add_and_enqueue(
+ node_id,
+ scope,
+ prompt,
+ status_message_id,
+ resolved_parent.node_id,
+ )
+ self._repository.register_node(
+ identity=tree.identity,
+ node_id=node_id,
+ status_message_id=status_message_id,
+ )
+ logger.info("Added node {} to tree {}", node_id, tree.identity)
+ else:
+ root = MessageNode(
+ node_id=node_id,
+ scope=scope,
+ prompt=prompt,
+ status_message_id=status_message_id,
+ state=MessageState.PENDING,
+ )
+ tree = MessageTree(root)
+ decision = await tree.enqueue_or_claim(node_id)
+ self._repository.add_tree(
+ tree,
+ node_id=node_id,
+ status_message_id=status_message_id,
+ )
+ logger.info("Created new tree {}", tree.identity)
- tree = MessageTree(root_node)
- self._repository.add_tree(node_id, tree)
+ if decision.claim is not None:
+ self._processor.launch(tree, decision.claim)
+ return decision
- logger.info(f"Created new tree with root {node_id}")
- return tree
+ async def resolve_reply(
+ self,
+ scope: MessageScope,
+ reference_id: str,
+ ) -> ReplyTarget | None:
+ """Resolve a scoped node or status-message reference."""
+ async with self._lock:
+ tree = self._repository.get_tree_for_reference(scope, reference_id)
+ return await tree.resolve_reply(reference_id) if tree is not None else None
- async def add_to_tree(
+ async def resolve_node_id(
self,
- parent_node_id: str,
- node_id: str,
- incoming: IncomingMessage,
- status_message_id: str,
- ) -> tuple[MessageTree, MessageNode]:
- """
- Add a reply as a child node to an existing tree.
-
- Args:
- parent_node_id: ID of the parent message
- node_id: ID for the new node
- incoming: The incoming reply message
- status_message_id: Bot's status message ID
-
- Returns:
- Tuple of (tree, new_node)
- """
+ scope: MessageScope,
+ reference_id: str,
+ ) -> str | None:
+ target = await self.resolve_reply(scope, reference_id)
+ return target.node_id if target is not None else None
+
+ async def get_node(
+ self,
+ scope: MessageScope,
+ reference_id: str,
+ ) -> NodeView | None:
+ """Return an immutable node read model."""
async with self._lock:
- if not self._repository.has_node(parent_node_id):
- raise ValueError(f"Parent node {parent_node_id} not found in any tree")
-
- tree = self._repository.get_tree_for_node(parent_node_id)
- if not tree:
- raise ValueError(f"Parent node {parent_node_id} not found in any tree")
-
- node = await tree.add_node(
- node_id=node_id,
- incoming=incoming,
- status_message_id=status_message_id,
- parent_id=parent_node_id,
- )
+ tree = self._repository.get_tree_for_reference(scope, reference_id)
+ if tree is None:
+ return None
+ target = await tree.resolve_reply(reference_id)
+ return await tree.node_view(target.node_id) if target is not None else None
+ async def record_session(
+ self,
+ claim: NodeClaim,
+ session_id: str,
+ ) -> TreeSnapshot | None:
async with self._lock:
- self._repository.register_node(node_id, tree.root_id)
+ tree = self._repository.get_tree(claim.identity)
+ return (
+ await tree.record_session(claim.claim_id, session_id)
+ if tree is not None
+ else None
+ )
- logger.info(f"Added node {node_id} to tree {tree.root_id}")
- return tree, node
+ async def complete_claim(
+ self,
+ claim: NodeClaim,
+ session_id: str | None,
+ ) -> TreeSnapshot | None:
+ async with self._lock:
+ tree = self._repository.get_tree(claim.identity)
+ return (
+ await tree.complete_claim(claim.claim_id, session_id)
+ if tree is not None
+ else None
+ )
- def get_tree(self, root_id: str) -> MessageTree | None:
- """Get a tree by its root ID."""
- return self._repository.get_tree(root_id)
+ async def fail_claim(
+ self,
+ claim: NodeClaim,
+ *,
+ propagate: bool = True,
+ ) -> FailureResult:
+ return await self._fail_claim(claim, propagate=propagate)
- def get_tree_for_node(self, node_id: str) -> MessageTree | None:
- """Get the tree containing a given node."""
- return self._repository.get_tree_for_node(node_id)
+ async def _fail_claim(
+ self,
+ claim: NodeClaim,
+ *,
+ propagate: bool,
+ ) -> FailureResult:
+ async with self._lock:
+ tree = self._repository.get_tree(claim.identity)
+ result = (
+ await tree.fail_claim(
+ claim.claim_id,
+ propagate=propagate,
+ )
+ if tree is not None
+ else FailureResult(affected=(), queue_update=None, snapshot=None)
+ )
+ if result.queue_update is not None:
+ await self._processor.notify_queue_updated(result.queue_update)
+ return result
- def get_node(self, node_id: str) -> MessageNode | None:
- """Get a node from any tree."""
- return self._repository.get_node(node_id)
+ async def _handle_processor_failure(
+ self,
+ claim: NodeClaim,
+ ) -> None:
+ """Route an escaped runner failure through manager-owned effects."""
+ result = await self._fail_claim(claim, propagate=True)
+ if self._unexpected_failure_callback is None:
+ return
+ try:
+ self._unexpected_failure_callback(result)
+ except Exception as exc:
+ logger.warning(
+ "Unexpected messaging failure callback failed: {}",
+ type(exc).__name__,
+ )
- def resolve_parent_node_id(self, msg_id: str) -> str | None:
- """Resolve a message ID to the actual parent node ID."""
- return self._repository.resolve_parent_node_id(msg_id)
+ async def _finish_claim(self, tree: MessageTree, claim: NodeClaim) -> None:
+ """Serialize successor task publication with aggregate detachment."""
+ async with self._lock:
+ tree_is_published = self._repository.get_tree(claim.identity) is tree
+ completion = await tree.finish_and_claim_next(claim.claim_id)
+ if tree_is_published and completion.next_claim is not None:
+ self._processor.launch(
+ tree,
+ completion.next_claim,
+ announce_started=True,
+ queue=completion.queue,
+ )
- def is_tree_busy(self, root_id: str) -> bool:
- """Check if a tree is currently processing."""
- return self._repository.is_tree_busy(root_id)
+ @staticmethod
+ def _external_effects(
+ transition: TreeCancellation,
+ cancelled_task: CancelledTask | None,
+ ) -> tuple[CancellationEffect, ...]:
+ active_node_id = (
+ transition.active_claim.node.node_id
+ if transition.active_claim is not None
+ else None
+ )
+ return tuple(
+ CancellationEffect(
+ node=node,
+ ui_owner=(
+ CancellationUiOwner.RUNNER
+ if node.node_id == active_node_id
+ and cancelled_task is not None
+ and cancelled_task.runner_started
+ else CancellationUiOwner.WORKFLOW
+ ),
+ )
+ for node in transition.nodes
+ )
- def is_node_tree_busy(self, node_id: str) -> bool:
- """Check if the tree containing a node is busy."""
- return self._repository.is_node_tree_busy(node_id)
+ async def _current_snapshot(
+ self,
+ identity: TreeIdentity,
+ expected_tree: MessageTree,
+ ) -> TreeSnapshot | None:
+ async with self._lock:
+ tree = self._repository.get_tree(identity)
+ if tree is not expected_tree:
+ return None
+ return await tree.snapshot()
- async def enqueue(
+ async def cancel_node(
self,
+ scope: MessageScope,
node_id: str,
- processor: Callable[[str, MessageNode], Awaitable[None]],
- ) -> bool:
- """
- Enqueue a node for processing.
-
- If the tree is not busy, processing starts immediately.
- If busy, the message is queued.
+ *,
+ reason: CancellationReason | None = None,
+ ) -> CancellationResult:
+ return await _finish_transition(self._cancel_node(scope, node_id, reason))
- Args:
- node_id: Node to process
- processor: Async function to process the node
-
- Returns:
- True if queued, False if processing immediately
- """
- tree = self._repository.get_tree_for_node(node_id)
- if not tree:
- logger.error(f"No tree found for node {node_id}")
- return False
-
- return await self._processor.enqueue_and_start(tree, node_id, processor)
-
- def get_queue_size(self, node_id: str) -> int:
- """Get queue size for the tree containing a node."""
- return self._repository.get_queue_size(node_id)
-
- def get_pending_children(self, node_id: str) -> list[MessageNode]:
- """Get all pending child nodes (recursively) of a given node."""
- return self._repository.get_pending_children(node_id)
-
- async def mark_node_error(
+ async def _cancel_node(
self,
+ scope: MessageScope,
node_id: str,
- error_message: str,
- propagate_to_children: bool = True,
- ) -> list[MessageNode]:
- """
- Mark a node as ERROR and optionally propagate to pending children.
-
- Args:
- node_id: The node to mark as error
- error_message: Error description
- propagate_to_children: If True, also mark pending children as error
-
- Returns:
- List of all nodes marked as error (including children)
- """
- tree = self._repository.get_tree_for_node(node_id)
- if not tree:
- return []
-
- affected = []
- node = tree.get_node(node_id)
- if node:
- await tree.update_state(
- node_id, MessageState.ERROR, error_message=error_message
- )
- affected.append(node)
-
- if propagate_to_children:
- pending_children = self._repository.get_pending_children(node_id)
- for child in pending_children:
- await tree.update_state(
- child.node_id,
- MessageState.ERROR,
- error_message=f"Parent failed: {error_message}",
- )
- affected.append(child)
-
- return affected
-
- async def cancel_tree(
- self, root_id: str, *, reason: CancellationReason | None = None
- ) -> list[CancelledNode]:
- """
- Cancel all queued and in-progress messages in a tree.
-
- Updates node states to ERROR and returns list of affected nodes
- that were actually active or in the current processing queue.
- """
- tree = self._repository.get_tree(root_id)
- if not tree:
- return []
-
- cancelled_nodes: list[CancelledNode] = []
- cancelled_tasks: list[asyncio.Task] = []
-
- cleanup_count = 0
- async with tree.with_lock():
- current_id = tree.current_node_id
- current_node = tree.get_node(current_id) if current_id else None
- if current_node is not None:
- set_cancel_reason(current_node, reason)
- cancelled_task = tree.cancel_current_task()
- if cancelled_task:
- cancelled_tasks.append(cancelled_task)
- if current_node and current_node.state not in (
- MessageState.COMPLETED,
- MessageState.ERROR,
- ):
- tree.set_node_error_sync(current_node, "Cancelled by user")
- cancelled_nodes.append(
- CancelledNode(current_node, CancellationUiOwner.RUNNER)
- )
-
- queue_nodes = tree.drain_queue_and_mark_cancelled()
- for node in queue_nodes:
- set_cancel_reason(node, reason)
- cancelled_nodes.extend(
- CancelledNode(node, CancellationUiOwner.WORKFLOW)
- for node in queue_nodes
- )
- cancelled_ids = {entry.node.node_id for entry in cancelled_nodes}
-
- for node in tree.all_nodes():
- if (
- node.state in (MessageState.PENDING, MessageState.IN_PROGRESS)
- and node.node_id not in cancelled_ids
- ):
- set_cancel_reason(node, reason)
- tree.set_node_error_sync(node, "Stale task cleaned up")
- cancelled_nodes.append(
- CancelledNode(node, CancellationUiOwner.WORKFLOW)
- )
- cleanup_count += 1
-
- tree.reset_processing_state()
-
- await _drain_cancelled_tasks(cancelled_tasks)
-
- if cancelled_nodes:
- logger.info(
- f"Cancelled {len(cancelled_nodes)} active nodes in tree {root_id}"
+ reason: CancellationReason | None,
+ ) -> CancellationResult:
+ async with self._lock:
+ tree = self._repository.get_tree_for_reference(scope, node_id)
+ if tree is None:
+ return CancellationResult()
+ target = await tree.resolve_reply(node_id)
+ if target is None:
+ return CancellationResult()
+ transition = await tree.cancel_node(target.node_id)
+ cancelled_task = (
+ self._processor.cancel(transition.active_claim, reason)
+ if transition.active_claim is not None
+ else None
)
- if cleanup_count:
- logger.info(f"Cleaned up {cleanup_count} stale nodes in tree {root_id}")
-
- return cancelled_nodes
-
- async def cancel_node(
- self, node_id: str, *, reason: CancellationReason | None = None
- ) -> list[CancelledNode]:
- """
- Cancel a single node (queued or in-progress) without affecting other nodes.
-
- Returns:
- List containing the cancelled node if it was cancellable, else empty list.
- """
- tree = self._repository.get_tree_for_node(node_id)
- if not tree:
- return []
-
- async with tree.with_lock():
- node = tree.get_node(node_id)
- if not node:
- return []
-
- if node.state in (MessageState.COMPLETED, MessageState.ERROR):
- return []
-
- set_cancel_reason(node, reason)
- cancelled_tasks: list[asyncio.Task] = []
- ui_owner = CancellationUiOwner.WORKFLOW
- if tree.is_current_node(node_id):
- cancelled_task = self._processor.cancel_current(tree)
- if cancelled_task:
- cancelled_tasks.append(cancelled_task)
- ui_owner = CancellationUiOwner.RUNNER
-
- removed_from_queue = False
- try:
- removed_from_queue = tree.remove_from_queue(node_id)
- except Exception:
- logger.debug(
- "Failed to remove node from queue; will rely on state=ERROR"
- )
- tree.set_node_error_sync(node, "Cancelled by user")
-
- if removed_from_queue:
- await self._processor.notify_queue_updated(tree)
- await _drain_cancelled_tasks(cancelled_tasks)
-
- return [CancelledNode(node, ui_owner)]
+ if transition.queue_update is not None:
+ await self._processor.notify_queue_updated(transition.queue_update)
+ if cancelled_task is not None:
+ await _drain_cancelled_tasks([cancelled_task.task])
+ snapshot = await self._current_snapshot(tree.identity, tree)
+ return CancellationResult(
+ effects=self._external_effects(transition, cancelled_task),
+ snapshots=(snapshot,) if snapshot is not None else (),
+ )
async def cancel_all(
- self, *, reason: CancellationReason | None = None
- ) -> list[CancelledNode]:
- """Cancel all messages in all trees."""
+ self,
+ *,
+ reason: CancellationReason | None = None,
+ ) -> CancellationResult:
+ return await _finish_transition(self._cancel_all(reason))
+
+ async def _cancel_all(
+ self,
+ reason: CancellationReason | None,
+ ) -> CancellationResult:
+ transitions: list[
+ tuple[MessageTree, TreeCancellation, CancelledTask | None]
+ ] = []
async with self._lock:
- root_ids = list(self._repository.tree_ids())
- all_cancelled: list[CancelledNode] = []
- for root_id in root_ids:
- all_cancelled.extend(await self.cancel_tree(root_id, reason=reason))
- return all_cancelled
-
- def cleanup_stale_nodes(self) -> int:
- """
- Mark any PENDING or IN_PROGRESS nodes in all trees as ERROR.
- Used on startup to reconcile restored state.
- """
- count = 0
- for tree in self._repository.all_trees():
- for node in tree.all_nodes():
- if node.state in (MessageState.PENDING, MessageState.IN_PROGRESS):
- tree.set_node_error_sync(node, "Lost during server restart")
- count += 1
- if count:
- logger.info(f"Cleaned up {count} stale nodes during startup")
- return count
+ for tree in self._repository.trees():
+ transition = await tree.cancel_all()
+ cancelled_task = (
+ self._processor.cancel(transition.active_claim, reason)
+ if transition.active_claim is not None
+ else None
+ )
+ transitions.append((tree, transition, cancelled_task))
+
+ for _tree, transition, _task in transitions:
+ if transition.queue_update is not None:
+ await self._processor.notify_queue_updated(transition.queue_update)
+ await _drain_cancelled_tasks(
+ [
+ cancelled.task
+ for _tree, _transition, cancelled in transitions
+ if cancelled is not None
+ ]
+ )
- def get_tree_count(self) -> int:
- """Get the number of active message trees."""
- return self._repository.tree_count()
+ effects: list[CancellationEffect] = []
+ snapshots: list[TreeSnapshot] = []
+ for tree, transition, cancelled_task in transitions:
+ effects.extend(self._external_effects(transition, cancelled_task))
+ snapshot = await self._current_snapshot(tree.identity, tree)
+ if snapshot is not None:
+ snapshots.append(snapshot)
+ return CancellationResult(effects=tuple(effects), snapshots=tuple(snapshots))
- def set_queue_update_callback(
+ async def clear_all(
self,
- queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None,
- ) -> None:
- """Set callback for queue position updates."""
- self._processor.set_queue_update_callback(queue_update_callback)
+ *,
+ reason: CancellationReason | None = None,
+ ) -> CancellationResult:
+ """Atomically detach all trees, then drain their exact active tasks."""
+ return await _finish_transition(self._clear_all(reason))
- def set_node_started_callback(
+ async def _clear_all(
self,
- node_started_callback: Callable[[MessageTree, str], Awaitable[None]] | None,
- ) -> None:
- """Set callback for when a queued node starts processing."""
- self._processor.set_node_started_callback(node_started_callback)
-
- def register_node(self, node_id: str, root_id: str) -> None:
- """Register a node ID to a tree (for external mapping)."""
- self._repository.register_node(node_id, root_id)
-
- async def cancel_branch(
- self, branch_root_id: str, *, reason: CancellationReason | None = None
- ) -> list[CancelledNode]:
- """
- Cancel all PENDING/IN_PROGRESS nodes in the subtree (branch_root + descendants).
- """
- tree = self._repository.get_tree_for_node(branch_root_id)
- if not tree:
- return []
-
- branch_ids = set(tree.get_descendants(branch_root_id))
- cancelled: list[CancelledNode] = []
- cancelled_tasks: list[asyncio.Task] = []
- removed_from_queue = False
-
- async with tree.with_lock():
- for nid in branch_ids:
- node = tree.get_node(nid)
- if not node or node.state in (
- MessageState.COMPLETED,
- MessageState.ERROR,
- ):
- continue
-
- if tree.is_current_node(nid):
- set_cancel_reason(node, reason)
- cancelled_task = self._processor.cancel_current(tree)
- ui_owner = CancellationUiOwner.WORKFLOW
- if cancelled_task:
- cancelled_tasks.append(cancelled_task)
- ui_owner = CancellationUiOwner.RUNNER
- tree.set_node_error_sync(node, "Cancelled by user")
- cancelled.append(CancelledNode(node, ui_owner))
- else:
- set_cancel_reason(node, reason)
- removed_from_queue = (
- tree.remove_from_queue(nid) or removed_from_queue
- )
- tree.set_node_error_sync(node, "Cancelled by user")
- cancelled.append(CancelledNode(node, CancellationUiOwner.WORKFLOW))
-
- 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)
- await _drain_cancelled_tasks(cancelled_tasks)
- return cancelled
+ reason: CancellationReason | None,
+ ) -> CancellationResult:
+ transitions: list[tuple[TreeCancellation, CancelledTask | None]] = []
+ async with self._lock:
+ for tree in self._repository.trees():
+ transition = await tree.cancel_all()
+ cancelled_task = (
+ self._processor.cancel(transition.active_claim, reason)
+ if transition.active_claim is not None
+ else None
+ )
+ transitions.append((transition, cancelled_task))
+ self._repository = TreeRepository()
+
+ await _drain_cancelled_tasks(
+ [
+ cancelled.task
+ for _transition, cancelled in transitions
+ if cancelled is not None
+ ]
+ )
+ effects: list[CancellationEffect] = []
+ for transition, cancelled_task in transitions:
+ effects.extend(self._external_effects(transition, cancelled_task))
+ return CancellationResult(effects=tuple(effects))
async def remove_branch(
- self, branch_root_id: str
- ) -> tuple[list[MessageNode], str, bool]:
- """
- Remove a branch (subtree) from the tree.
-
- If branch_root is the tree root, removes the entire tree.
-
- Returns:
- (removed_nodes, root_id, removed_entire_tree)
- """
- tree = self._repository.get_tree_for_node(branch_root_id)
- if not tree:
- return ([], "", False)
+ self,
+ scope: MessageScope,
+ branch_root_id: str,
+ *,
+ reason: CancellationReason | None = None,
+ ) -> BranchRemovalResult:
+ """Atomically cancel, detach, and unindex one scoped branch."""
+ return await _finish_transition(
+ self._remove_branch(scope, branch_root_id, reason)
+ )
- root_id = tree.root_id
+ async def _remove_branch(
+ self,
+ scope: MessageScope,
+ branch_root_id: str,
+ reason: CancellationReason | None,
+ ) -> BranchRemovalResult:
+ async with self._lock:
+ tree = self._repository.get_tree_for_reference(scope, branch_root_id)
+ if tree is None:
+ return BranchRemovalResult(
+ cancellation=CancellationResult(),
+ removed_tree_identity=None,
+ message_ids=frozenset(),
+ )
+ target = await tree.resolve_reply(branch_root_id)
+ if target is None:
+ return BranchRemovalResult(
+ cancellation=CancellationResult(),
+ removed_tree_identity=None,
+ message_ids=frozenset(),
+ )
+ identity = tree.identity
+ transition = await tree.remove_branch(target.node_id)
+ lookup_ids = set(transition.message_ids)
+ if transition.removed_entire_tree:
+ self._repository.remove_tree(identity)
+ else:
+ self._repository.unregister_references(identity, lookup_ids)
+ cancelled_task = (
+ self._processor.cancel(transition.cancellation.active_claim, reason)
+ if transition.cancellation.active_claim is not None
+ else None
+ )
- if branch_root_id == root_id:
- cancelled = await self.cancel_tree(root_id)
- removed_tree = self._repository.remove_tree(root_id)
- if removed_tree:
- return (removed_tree.all_nodes(), root_id, True)
- return ([entry.node for entry in cancelled], root_id, True)
+ if transition.cancellation.queue_update is not None:
+ await self._processor.notify_queue_updated(
+ transition.cancellation.queue_update
+ )
+ if cancelled_task is not None:
+ await _drain_cancelled_tasks([cancelled_task.task])
+ snapshot = (
+ None
+ if transition.removed_entire_tree
+ else await self._current_snapshot(identity, tree)
+ )
+ cancellation = CancellationResult(
+ effects=self._external_effects(
+ transition.cancellation,
+ cancelled_task,
+ ),
+ snapshots=(snapshot,) if snapshot is not None else (),
+ )
+ return BranchRemovalResult(
+ cancellation=cancellation,
+ removed_tree_identity=(
+ identity if transition.removed_entire_tree else None
+ ),
+ message_ids=transition.message_ids,
+ )
- async with tree.with_lock():
- removed = tree.remove_branch(branch_root_id)
+ def get_tree_count(self) -> int:
+ return self._repository.tree_count()
- self._repository.unregister_node_lookups(removed)
- return (removed, root_id, False)
+ def task_count(self) -> int:
+ return self._processor.task_count()
- def get_message_ids_for_chat(self, platform: str, chat_id: str) -> set[str]:
- """Get all message IDs for a given platform/chat."""
- return self._repository.get_message_ids_for_chat(platform, chat_id)
+ async def get_message_ids_for_chat(self, platform: str, chat_id: str) -> set[str]:
+ async with self._lock:
+ message_ids: set[str] = set()
+ for tree in self._repository.trees():
+ message_ids.update(await tree.message_ids_for_chat(platform, chat_id))
+ return message_ids
- def snapshot(self) -> ConversationSnapshot:
- """Serialize all trees into a typed conversation snapshot."""
- return self._repository.snapshot()
+ async def snapshot(self) -> ConversationSnapshot:
+ async with self._lock:
+ trees: dict[TreeIdentity, TreeSnapshot] = {}
+ for tree in self._repository.trees():
+ trees[tree.identity] = await tree.snapshot()
+ return ConversationSnapshot(trees=trees)
@classmethod
def from_snapshot(
cls,
snapshot: ConversationSnapshot,
- queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None = None,
- node_started_callback: Callable[[MessageTree, str], Awaitable[None]]
- | None = None,
+ node_processor: NodeProcessor,
+ *,
+ queue_update_callback: QueueUpdateCallback | None = None,
+ node_started_callback: NodeStartedCallback | None = None,
+ unexpected_failure_callback: Callable[[FailureResult], None] | None = None,
) -> TreeQueueManager:
- """Restore a manager from a typed conversation snapshot."""
+ repository, normalized, stale_targets = TreeRepository.from_snapshot(snapshot)
return cls(
+ node_processor,
queue_update_callback=queue_update_callback,
node_started_callback=node_started_callback,
- _repository=TreeRepository.from_snapshot(snapshot),
+ unexpected_failure_callback=unexpected_failure_callback,
+ _repository=repository,
+ _restored_snapshot=normalized,
+ _restored_stale_targets=stale_targets,
)
-__all__ = [
- "TreeQueueManager",
-]
+__all__ = ["TreeQueueManager"]
diff --git a/src/free_claude_code/messaging/trees/node.py b/src/free_claude_code/messaging/trees/node.py
index 1b41b73e..c2655008 100644
--- a/src/free_claude_code/messaging/trees/node.py
+++ b/src/free_claude_code/messaging/trees/node.py
@@ -1,11 +1,9 @@
"""Message tree node model."""
from dataclasses import dataclass, field
-from datetime import UTC, datetime
from enum import Enum
-from typing import Any
-from ..models import IncomingMessage
+from ..models import MessageScope
class MessageState(Enum):
@@ -22,36 +20,23 @@ class MessageNode:
"""A single user prompt/status node in a messaging conversation tree."""
node_id: str
- incoming: IncomingMessage
+ scope: MessageScope
+ prompt: str
status_message_id: str
state: MessageState = MessageState.PENDING
parent_id: str | None = None
session_id: str | None = None
children_ids: list[str] = field(default_factory=list)
- created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
- completed_at: datetime | None = None
- error_message: str | None = None
- context: Any = None
-
- def set_context(self, context: Any) -> None:
- self.context = context
def update_state(
self,
state: MessageState,
*,
session_id: str | None = None,
- error_message: str | None = None,
) -> None:
self.state = state
if session_id:
self.session_id = session_id
- if error_message is not None:
- self.error_message = error_message
- elif state == MessageState.COMPLETED:
- self.error_message = None
- if state in (MessageState.COMPLETED, MessageState.ERROR):
- self.completed_at = datetime.now(UTC)
-
- def mark_error(self, error_message: str) -> None:
- self.update_state(MessageState.ERROR, error_message=error_message)
+
+ def mark_error(self) -> None:
+ self.update_state(MessageState.ERROR)
diff --git a/src/free_claude_code/messaging/trees/processor.py b/src/free_claude_code/messaging/trees/processor.py
index 4af4546c..c12135e8 100644
--- a/src/free_claude_code/messaging/trees/processor.py
+++ b/src/free_claude_code/messaging/trees/processor.py
@@ -1,180 +1,227 @@
-"""Async processing loop for a single messaging tree queue."""
+"""Task execution for claims returned by messaging tree aggregates."""
import asyncio
+import contextlib
from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
from loguru import logger
from free_claude_code.config.settings import get_settings
-from free_claude_code.core.diagnostics import safe_exception_message
from ..safe_diagnostics import format_exception_for_log
-from .node import MessageNode, MessageState
from .runtime import MessageTree
+from .transitions import CancellationReason, NodeClaim, QueueEntry
+
+NodeProcessor = Callable[[NodeClaim], Awaitable[None]]
+QueueUpdateCallback = Callable[[tuple[QueueEntry, ...]], Awaitable[None]]
+NodeStartedCallback = Callable[[NodeClaim], Awaitable[None]]
+ClaimFailureCallback = Callable[[NodeClaim], Awaitable[None]]
+ClaimFinishedCallback = Callable[[MessageTree, NodeClaim], Awaitable[None]]
+
+
+@dataclass(slots=True)
+class _TaskSlot:
+ tree: MessageTree
+ claim: NodeClaim
+ task: asyncio.Task[None] | None = None
+ runner_started: bool = False
+ transitioned: bool = False
+ recovery_task: asyncio.Task[None] | None = None
+ cancellation_requested: bool = False
+ cancellation_reason: CancellationReason | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CancelledTask:
+ """Task handle plus whether the node runner owns cancellation UI."""
+
+ task: asyncio.Task[None]
+ runner_started: bool
class TreeQueueProcessor:
- """Per-tree async queue processing owned by TreeQueueManager."""
+ """Own asyncio tasks while MessageTree owns scheduling state."""
def __init__(
self,
- queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None = None,
- node_started_callback: Callable[[MessageTree, str], Awaitable[None]]
- | None = None,
+ node_processor: NodeProcessor,
+ *,
+ claim_failure_callback: ClaimFailureCallback,
+ claim_finished_callback: ClaimFinishedCallback,
+ queue_update_callback: QueueUpdateCallback | None = None,
+ node_started_callback: NodeStartedCallback | None = None,
) -> None:
+ self._node_processor = node_processor
+ self._claim_failure_callback = claim_failure_callback
+ self._claim_finished_callback = claim_finished_callback
self._queue_update_callback = queue_update_callback
self._node_started_callback = node_started_callback
+ self._tasks: dict[str, _TaskSlot] = {}
- 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
+ @staticmethod
+ def _key(claim: NodeClaim) -> str:
+ return claim.claim_id
- def set_node_started_callback(
+ def launch(
self,
- node_started_callback: Callable[[MessageTree, str], Awaitable[None]] | None,
+ tree: MessageTree,
+ claim: NodeClaim,
+ *,
+ announce_started: bool = False,
+ queue: tuple[QueueEntry, ...] = (),
) -> None:
- """Update the callback used when a queued node starts processing."""
- self._node_started_callback = node_started_callback
+ """Attach a task synchronously before another coroutine can cancel it."""
+ key = self._key(claim)
+ if key in self._tasks:
+ raise RuntimeError(f"Claim {key} already has a task")
+ slot = _TaskSlot(tree=tree, claim=claim)
+ self._tasks[key] = slot
+ try:
+ task = asyncio.create_task(
+ self._run_claim(
+ slot,
+ announce_started=announce_started,
+ queue=queue,
+ ),
+ name=(f"messaging-claim-{claim.identity.root_id}-{claim.claim_id[:8]}"),
+ eager_start=False,
+ )
+ except BaseException:
+ self._tasks.pop(key, None)
+ raise
+ slot.task = task
+ task.add_done_callback(lambda _task, claim_key=key: self._task_done(claim_key))
- async def _notify_queue_updated(self, tree: MessageTree) -> None:
- """Invoke queue update callback if set."""
- if not self._queue_update_callback:
+ def _task_done(self, key: str) -> None:
+ """Recover a claim if its task was cancelled before entering its body."""
+ slot = self._tasks.get(key)
+ if slot is None or slot.transitioned or slot.recovery_task is not None:
+ return
+ slot.recovery_task = asyncio.create_task(
+ self._recover_unentered_task(slot),
+ name=f"messaging-claim-recovery-{key[:8]}",
+ )
+
+ async def _recover_unentered_task(self, slot: _TaskSlot) -> None:
+ task = slot.task
+ if task is not None:
+ with contextlib.suppress(asyncio.CancelledError, Exception):
+ await task
+ if not slot.transitioned:
+ await self._finish_and_continue(slot)
+
+ async def _notify_queue_updated(self, queue: tuple[QueueEntry, ...]) -> None:
+ if self._queue_update_callback is None:
return
try:
- await self._queue_update_callback(tree)
- except Exception as e:
- d = get_settings().log_messaging_error_details
+ await self._queue_update_callback(queue)
+ except Exception as exc:
+ details = get_settings().log_messaging_error_details
logger.warning(
"Queue update callback failed: {}",
- format_exception_for_log(e, log_full_message=d),
+ format_exception_for_log(exc, log_full_message=details),
)
- 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_queue_updated(self, queue: tuple[QueueEntry, ...]) -> None:
+ """Publish a transition-owned queue snapshot."""
+ await self._notify_queue_updated(queue)
- async def _notify_node_started(self, tree: MessageTree, node_id: str) -> None:
- """Invoke node started callback if set."""
- if not self._node_started_callback:
+ async def _notify_node_started(self, claim: NodeClaim) -> None:
+ if self._node_started_callback is None:
return
try:
- await self._node_started_callback(tree, node_id)
- except Exception as e:
- d = get_settings().log_messaging_error_details
+ await self._node_started_callback(claim)
+ except Exception as exc:
+ details = get_settings().log_messaging_error_details
logger.warning(
"Node started callback failed: {}",
- format_exception_for_log(e, log_full_message=d),
+ format_exception_for_log(exc, log_full_message=details),
)
- async def process_node(
+ async def _run_claim(
self,
- tree: MessageTree,
- node: MessageNode,
- processor: Callable[[str, MessageNode], Awaitable[None]],
+ slot: _TaskSlot,
+ *,
+ announce_started: bool,
+ queue: tuple[QueueEntry, ...],
) -> 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
-
+ claim = slot.claim
try:
- await processor(node.node_id, node)
+ if announce_started:
+ await self._notify_node_started(claim)
+ await self._notify_queue_updated(queue)
+ if slot.cancellation_requested:
+ if slot.cancellation_reason is None:
+ raise asyncio.CancelledError
+ raise asyncio.CancelledError(slot.cancellation_reason)
+ slot.runner_started = True
+ await self._node_processor(claim)
except asyncio.CancelledError:
- logger.info(f"Task for node {node.node_id} was cancelled")
+ logger.info("Task for node {} was cancelled", claim.node.node_id)
raise
- except Exception as e:
- d = get_settings().log_messaging_error_details
+ except Exception as exc:
+ details = 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=safe_exception_message(e),
+ claim.node.node_id,
+ format_exception_for_log(exc, log_full_message=details),
)
+ await self._claim_failure_callback(claim)
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(
+ if not slot.transitioned:
+ await self._finish_and_continue(slot)
+
+ async def _finish_and_continue(self, slot: _TaskSlot) -> None:
+ current = asyncio.current_task()
+ if current is not None:
+ while current.cancelling():
+ current.uncancel()
+ while True:
+ try:
+ await self._claim_finished_callback(slot.tree, slot.claim)
+ break
+ except asyncio.CancelledError:
+ if current is not None:
+ while current.cancelling():
+ current.uncancel()
+ continue
+
+ slot.transitioned = True
+ self._tasks.pop(self._key(slot.claim), None)
+
+ def cancel(
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) -> asyncio.Task | None:
- """Cancel the currently running task in a tree."""
- return tree.cancel_current_task()
-
-
-__all__ = ["TreeQueueProcessor"]
+ claim: NodeClaim,
+ reason: CancellationReason | None,
+ ) -> CancelledTask | None:
+ """Cancel exactly the task bound to one aggregate claim."""
+ slot = self._tasks.get(self._key(claim))
+ if slot is None:
+ return None
+ slot.cancellation_requested = True
+ slot.cancellation_reason = reason
+ task = slot.task
+ if task is None or task.done():
+ return None
+ if reason is None:
+ task.cancel()
+ else:
+ task.cancel(reason)
+
+ if slot.runner_started:
+ return CancelledTask(task=task, runner_started=True)
+
+ if slot.recovery_task is None:
+ slot.recovery_task = asyncio.create_task(
+ self._recover_unentered_task(slot),
+ name=f"messaging-claim-recovery-{claim.claim_id[:8]}",
+ )
+ return CancelledTask(task=slot.recovery_task, runner_started=False)
+
+ def task_count(self) -> int:
+ """Return the number of attached claims for observability."""
+ return len(self._tasks)
+
+
+__all__ = ["CancelledTask", "TreeQueueProcessor"]
diff --git a/src/free_claude_code/messaging/trees/queue.py b/src/free_claude_code/messaging/trees/queue.py
index cefc4580..c7bafdcf 100644
--- a/src/free_claude_code/messaging/trees/queue.py
+++ b/src/free_claude_code/messaging/trees/queue.py
@@ -1,6 +1,5 @@
"""FIFO queue state for one messaging conversation tree."""
-import asyncio
from collections import deque
@@ -11,15 +10,19 @@ class MessageNodeQueue:
self._deque: deque[str] = deque()
self._set: set[str] = set()
for item in items or []:
- self.put_nowait(item)
+ self.put(item)
- def put_nowait(self, item: str) -> None:
+ def put(self, item: str) -> bool:
+ """Append a unique item and report whether the queue changed."""
+ if item in self._set:
+ return False
self._deque.append(item)
self._set.add(item)
+ return True
- def get_nowait(self) -> str:
+ def pop(self) -> str | None:
if not self._deque:
- raise asyncio.QueueEmpty()
+ return None
item = self._deque.popleft()
self._set.discard(item)
return item
@@ -27,18 +30,18 @@ class MessageNodeQueue:
def qsize(self) -> int:
return len(self._deque)
- def snapshot(self) -> list[str]:
- return list(self._deque)
+ def items(self) -> tuple[str, ...]:
+ return tuple(self._deque)
- def remove_if_present(self, item: str) -> bool:
+ def remove(self, item: str) -> bool:
if item not in self._set:
return False
self._set.discard(item)
self._deque = deque(x for x in self._deque if x != item)
return True
- def drain(self) -> list[str]:
- items = list(self._deque)
+ def drain(self) -> tuple[str, ...]:
+ items = tuple(self._deque)
self._deque.clear()
self._set.clear()
return items
diff --git a/src/free_claude_code/messaging/trees/repository.py b/src/free_claude_code/messaging/trees/repository.py
index 5c9dfa7f..c7e60ec4 100644
--- a/src/free_claude_code/messaging/trees/repository.py
+++ b/src/free_claude_code/messaging/trees/repository.py
@@ -1,178 +1,135 @@
-"""In-memory repository for messaging trees and node indexes."""
+"""Manager-owned index of messaging tree aggregates."""
from loguru import logger
-from .node import MessageNode, MessageState
+from ..models import MessageScope
+from .identity import TreeIdentity
from .runtime import MessageTree
from .snapshot import ConversationSnapshot
+from .transitions import NodeUiTarget
class TreeRepository:
- """
- In-memory index of trees and node-to-root mappings.
-
- Used only by TreeQueueManager; kept as a named type for focused tests.
- """
+ """Store aggregates and map node/status references to their root."""
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:
+ self._trees: dict[TreeIdentity, MessageTree] = {}
+ self._reference_to_tree: dict[tuple[MessageScope, str], TreeIdentity] = {}
+
+ def get_tree(self, identity: TreeIdentity) -> MessageTree | None:
+ return self._trees.get(identity)
+
+ def get_tree_for_reference(
+ self,
+ scope: MessageScope,
+ reference_id: str,
+ ) -> MessageTree | None:
+ identity = self._reference_to_tree.get((scope, reference_id))
+ return self._trees.get(identity) if identity is not None else None
+
+ def has_reference(self, scope: MessageScope, reference_id: str) -> bool:
+ return (scope, reference_id) in self._reference_to_tree
+
+ def add_tree(
+ self,
+ tree: MessageTree,
+ *,
+ node_id: str,
+ status_message_id: str,
+ ) -> None:
+ identity = tree.identity
+ if identity in self._trees:
+ raise ValueError(f"Tree {identity} already exists")
+ self.register_node(
+ identity=identity,
+ node_id=node_id,
+ status_message_id=status_message_id,
+ )
+ self._trees[identity] = tree
+ logger.debug("TREE_REPO: add_tree identity={}", identity)
+
+ def register_node(
+ self,
+ *,
+ identity: TreeIdentity,
+ node_id: str,
+ status_message_id: str,
+ ) -> None:
+ if self.has_reference(identity.scope, node_id) or self.has_reference(
+ identity.scope, status_message_id
+ ):
+ raise ValueError("Node or status message is already registered")
+ self._reference_to_tree[(identity.scope, node_id)] = identity
+ self._reference_to_tree[(identity.scope, status_message_id)] = identity
+
+ def unregister_references(
+ self,
+ identity: TreeIdentity,
+ reference_ids: set[str],
+ ) -> None:
+ for reference_id in reference_ids:
+ key = (identity.scope, reference_id)
+ if self._reference_to_tree.get(key) == identity:
+ self._reference_to_tree.pop(key)
+
+ def remove_tree(
+ self,
+ identity: TreeIdentity,
+ ) -> MessageTree | None:
+ tree = self._trees.pop(identity, None)
+ if tree is None:
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)
+ self._reference_to_tree = {
+ key: owner
+ for key, owner in self._reference_to_tree.items()
+ if owner != identity
+ }
+ logger.debug("TREE_REPO: remove_tree identity={}", identity)
+ return tree
- 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 trees(self) -> tuple[MessageTree, ...]:
+ return tuple(self._trees.values())
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 snapshot(self) -> ConversationSnapshot:
- """Serialize all trees into a typed conversation snapshot."""
- return ConversationSnapshot(
- trees={root_id: tree.snapshot() for root_id, tree in self._trees.items()}
- )
-
@classmethod
- def from_snapshot(cls, snapshot: ConversationSnapshot) -> TreeRepository:
- """Restore repository state from a typed conversation snapshot."""
+ def from_snapshot(
+ cls, snapshot: ConversationSnapshot
+ ) -> tuple[
+ TreeRepository,
+ ConversationSnapshot,
+ tuple[NodeUiTarget, ...],
+ ]:
repo = cls()
- for root_id, tree_snapshot in snapshot.trees.items():
- repo._trees[root_id] = MessageTree.from_snapshot(tree_snapshot)
- repo._node_to_tree = snapshot.derive_node_to_tree()
- return repo
+ normalized = ConversationSnapshot()
+ stale_targets: list[NodeUiTarget] = []
+ for tree_snapshot in snapshot.trees.values():
+ try:
+ tree = MessageTree.from_snapshot(tree_snapshot)
+ except (KeyError, TypeError, ValueError) as exc:
+ logger.warning(
+ "Skipping invalid messaging tree snapshot: {}",
+ type(exc).__name__,
+ )
+ continue
+ references = tree_snapshot.lookup_ids()
+ if tree.identity in repo._trees or any(
+ repo.has_reference(tree.identity.scope, reference)
+ for reference in references
+ ):
+ logger.warning("Skipping duplicate messaging tree {}", tree.identity)
+ continue
+ repo._trees[tree.identity] = tree
+ for reference in references:
+ repo._reference_to_tree[(tree.identity.scope, reference)] = (
+ tree.identity
+ )
+ stale_targets.extend(tree.restored_stale_targets)
+ normalized_tree = tree.restored_snapshot
+ if normalized_tree is not None:
+ normalized = normalized.with_tree(normalized_tree)
+ return repo, normalized, tuple(stale_targets)
__all__ = ["TreeRepository"]
diff --git a/src/free_claude_code/messaging/trees/runtime.py b/src/free_claude_code/messaging/trees/runtime.py
index 33095f4c..f10aa8e1 100644
--- a/src/free_claude_code/messaging/trees/runtime.py
+++ b/src/free_claude_code/messaging/trees/runtime.py
@@ -1,33 +1,54 @@
-"""Runtime state for one messaging conversation tree."""
+"""Atomic runtime aggregate for one messaging conversation tree."""
import asyncio
-from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from uuid import uuid4
from loguru import logger
-from ..models import IncomingMessage
+from ..models import MessageScope
from .graph import MessageTreeGraph
+from .identity import TreeIdentity
from .node import MessageNode, MessageState
from .queue import MessageNodeQueue
from .snapshot import TreeSnapshot
+from .transitions import (
+ CompletionResult,
+ FailureResult,
+ NodeClaim,
+ NodeUiTarget,
+ NodeView,
+ QueueDecision,
+ QueueEntry,
+ ReplyTarget,
+ TreeBranchRemoval,
+ TreeCancellation,
+)
+
+
+@dataclass(slots=True)
+class _ActiveClaim:
+ """Runtime execution identity kept separate from the node's UI state."""
+
+ claim: NodeClaim
+ cancellation_requested: bool = False
class MessageTree:
- """Runtime aggregate for one ordered messaging conversation tree."""
+ """Own graph, queue, claim identity, and every concurrency invariant."""
def __init__(
self,
root_node: MessageNode,
*,
- queue: MessageNodeQueue | None = None,
graph: MessageTreeGraph | None = None,
) -> None:
self._graph = graph or MessageTreeGraph(root_node)
- self._queue = queue or MessageNodeQueue()
+ self._queue = MessageNodeQueue()
self._lock = asyncio.Lock()
- self._is_processing = False
- self._current_node_id: str | None = None
- self._current_task: asyncio.Task | None = None
+ self._active: _ActiveClaim | None = None
+ self._restored_snapshot: TreeSnapshot | None = None
+ self._restored_stale_targets: tuple[NodeUiTarget, ...] = ()
logger.debug("Created MessageTree with root {}", self.root_id)
@property
@@ -35,149 +56,421 @@ class MessageTree:
return self._graph.root_id
@property
- def is_processing(self) -> bool:
- return self._is_processing
+ def identity(self) -> TreeIdentity:
+ return self._graph.identity
@property
- def current_node_id(self) -> str | None:
- return self._current_node_id
+ def restored_snapshot(self) -> TreeSnapshot | None:
+ """Normalized startup snapshot captured before the tree is published."""
+ return self._restored_snapshot
+
+ @property
+ def restored_stale_targets(self) -> tuple[NodeUiTarget, ...]:
+ """UI targets normalized from runnable to interrupted on restore."""
+ return self._restored_stale_targets
+
+ def _ui_target(self, node: MessageNode) -> NodeUiTarget:
+ return NodeUiTarget(
+ scope=node.scope,
+ node_id=node.node_id,
+ status_message_id=node.status_message_id,
+ )
+
+ def _queue_entries(self) -> tuple[QueueEntry, ...]:
+ entries: list[QueueEntry] = []
+ for node_id in self._queue.items():
+ node = self._graph.get_node(node_id)
+ if node is None or node.state is not MessageState.PENDING:
+ continue
+ entries.append(
+ QueueEntry(node=self._ui_target(node), position=len(entries) + 1)
+ )
+ return tuple(entries)
+
+ def _claim(self, node: MessageNode) -> NodeClaim:
+ node.update_state(MessageState.IN_PROGRESS)
+ claim = NodeClaim(
+ identity=self.identity,
+ claim_id=uuid4().hex,
+ node=self._ui_target(node),
+ prompt=node.prompt,
+ parent_session_id=self._graph.get_parent_session_id(node.node_id),
+ )
+ self._active = _ActiveClaim(claim=claim)
+ return claim
+
+ def _enqueue_or_claim(self, node_id: str) -> QueueDecision:
+ node = self._graph.get_node(node_id)
+ if node is None or node.state is not MessageState.PENDING:
+ return QueueDecision(
+ claim=None,
+ position=None,
+ snapshot=None,
+ )
+
+ if self._active is None:
+ claim = self._claim(node)
+ return QueueDecision(
+ claim=claim,
+ position=None,
+ snapshot=self._graph.snapshot(),
+ )
- async def add_node(
+ if not self._queue.put(node_id):
+ return QueueDecision(
+ claim=None,
+ position=None,
+ snapshot=None,
+ )
+
+ position = self._queue.qsize()
+ logger.info("Queued node {}, position {}", node_id, position)
+ return QueueDecision(
+ claim=None,
+ position=position,
+ snapshot=self._graph.snapshot(),
+ )
+
+ async def enqueue_or_claim(self, node_id: str) -> QueueDecision:
+ """Atomically reject, queue, or exclusively claim an existing node."""
+ async with self._lock:
+ return self._enqueue_or_claim(node_id)
+
+ async def add_and_enqueue(
self,
node_id: str,
- incoming: IncomingMessage,
+ scope: MessageScope,
+ prompt: str,
status_message_id: str,
parent_id: str,
- ) -> MessageNode:
+ ) -> QueueDecision:
+ """Atomically add a reply and admit it to this tree."""
async with self._lock:
- return self._graph.add_node(
+ self._graph.add_node(
node_id=node_id,
- incoming=incoming,
+ scope=scope,
+ prompt=prompt,
status_message_id=status_message_id,
parent_id=parent_id,
)
+ return self._enqueue_or_claim(node_id)
- def get_node(self, node_id: str) -> MessageNode | None:
- return self._graph.get_node(node_id)
-
- def get_root(self) -> MessageNode:
- return self._graph.get_root()
-
- def get_children(self, node_id: str) -> list[MessageNode]:
- return self._graph.get_children(node_id)
-
- def get_parent(self, node_id: str) -> MessageNode | None:
- return self._graph.get_parent(node_id)
-
- def get_parent_session_id(self, node_id: str) -> str | None:
- return self._graph.get_parent_session_id(node_id)
+ async def finish_and_claim_next(self, claim_id: str) -> CompletionResult:
+ """Release only the matching claim and atomically select its successor."""
+ async with self._lock:
+ if self._active is None or self._active.claim.claim_id != claim_id:
+ return CompletionResult(
+ next_claim=None,
+ queue=self._queue_entries(),
+ )
+
+ self._active = None
+ next_claim: NodeClaim | None = None
+ while node_id := self._queue.pop():
+ node = self._graph.get_node(node_id)
+ if node is not None and node.state is MessageState.PENDING:
+ next_claim = self._claim(node)
+ break
+
+ return CompletionResult(
+ next_claim=next_claim,
+ queue=self._queue_entries(),
+ )
- async def update_state(
+ async def cancel_node(
self,
node_id: str,
- state: MessageState,
- session_id: str | None = None,
- error_message: str | None = None,
- ) -> None:
+ ) -> TreeCancellation:
+ """Atomically cancel one active, queued, or stale runnable node."""
async with self._lock:
- self._graph.update_node_state(
- node_id,
- state,
- session_id=session_id,
- error_message=error_message,
+ node = self._graph.get_node(node_id)
+ active_claim = (
+ self._active.claim
+ if self._active is not None
+ and self._active.claim.node.node_id == node_id
+ else None
+ )
+ if active_claim is not None:
+ active = self._active
+ if active is not None:
+ active.cancellation_requested = True
+ if node is None:
+ return TreeCancellation(
+ nodes=(),
+ active_claim=active_claim,
+ queue_update=None,
+ )
+
+ queue_changed = self._queue.remove(node_id)
+ cancelled_nodes: tuple[NodeUiTarget, ...] = ()
+ if node.state in (MessageState.PENDING, MessageState.IN_PROGRESS):
+ node.mark_error()
+ cancelled_nodes = (self._ui_target(node),)
+ elif node.state is MessageState.ERROR and active_claim is not None:
+ cancelled_nodes = (self._ui_target(node),)
+ return TreeCancellation(
+ nodes=cancelled_nodes,
+ active_claim=active_claim,
+ queue_update=self._queue_entries() if queue_changed else None,
)
- async def enqueue(self, node_id: str) -> int:
- async with self._lock:
- self._queue.put_nowait(node_id)
- position = self._queue.qsize()
- logger.debug("Enqueued node {}, position {}", node_id, position)
- return position
-
- async def dequeue(self) -> str | None:
- try:
- return self._queue.get_nowait()
- except asyncio.QueueEmpty:
- return None
-
- async def get_queue_snapshot(self) -> list[str]:
+ async def cancel_all(
+ self,
+ ) -> TreeCancellation:
+ """Atomically cancel every runnable node present at the transition."""
async with self._lock:
- return self._queue.snapshot()
-
- def get_queue_size(self) -> int:
- return self._queue.qsize()
-
- def remove_from_queue(self, node_id: str) -> bool:
- return self._queue.remove_if_present(node_id)
+ cancelled_nodes: list[NodeUiTarget] = []
+ seen: set[str] = set()
+ active_claim: NodeClaim | None = None
+
+ if self._active is not None:
+ active_claim = self._active.claim
+ self._active.cancellation_requested = True
+ active_node = self._graph.get_node(active_claim.node.node_id)
+ if active_node is not None and active_node.state in (
+ MessageState.PENDING,
+ MessageState.IN_PROGRESS,
+ ):
+ active_node.mark_error()
+ seen.add(active_node.node_id)
+ cancelled_nodes.append(self._ui_target(active_node))
+ elif active_node is not None:
+ seen.add(active_node.node_id)
+ if active_node.state is MessageState.ERROR:
+ cancelled_nodes.append(self._ui_target(active_node))
+
+ queued_ids = self._queue.drain()
+ for node_id in queued_ids:
+ node = self._graph.get_node(node_id)
+ if node is None or node.state not in (
+ MessageState.PENDING,
+ MessageState.IN_PROGRESS,
+ ):
+ continue
+ node.mark_error()
+ seen.add(node_id)
+ cancelled_nodes.append(self._ui_target(node))
+
+ for node in self._graph.all_nodes():
+ if node.node_id in seen or node.state not in (
+ MessageState.PENDING,
+ MessageState.IN_PROGRESS,
+ ):
+ continue
+ node.mark_error()
+ cancelled_nodes.append(self._ui_target(node))
+
+ return TreeCancellation(
+ nodes=tuple(cancelled_nodes),
+ active_claim=active_claim,
+ queue_update=() if queued_ids else None,
+ )
- @asynccontextmanager
- async def with_lock(self):
+ async def remove_branch(
+ self,
+ branch_root_id: str,
+ ) -> TreeBranchRemoval:
+ """Atomically cancel and detach one subtree before external effects."""
async with self._lock:
- yield
-
- def set_processing_state(self, node_id: str | None, is_processing: bool) -> None:
- self._is_processing = is_processing
- self._current_node_id = node_id if is_processing else None
-
- def clear_current_node(self) -> None:
- self._current_node_id = None
-
- def is_current_node(self, node_id: str) -> bool:
- return self._current_node_id == node_id
+ branch_ids = tuple(self._graph.get_descendants(branch_root_id))
+ if not branch_ids:
+ empty = TreeCancellation(
+ nodes=(),
+ active_claim=None,
+ queue_update=None,
+ )
+ return TreeBranchRemoval(
+ cancellation=empty,
+ message_ids=frozenset(),
+ removed_entire_tree=False,
+ )
+
+ branch_set = set(branch_ids)
+ active_claim = (
+ self._active.claim
+ if self._active is not None
+ and self._active.claim.node.node_id in branch_set
+ else None
+ )
+ if active_claim is not None:
+ active = self._active
+ if active is not None:
+ active.cancellation_requested = True
+ cancelled_nodes: list[NodeUiTarget] = []
+ message_ids: set[str] = set()
+ queue_changed = False
+
+ for node_id in branch_ids:
+ node = self._graph.get_node(node_id)
+ if node is None:
+ continue
+ message_ids.add(node.node_id)
+ if node.status_message_id:
+ message_ids.add(str(node.status_message_id))
+ queue_changed = self._queue.remove(node_id) or queue_changed
+ if node.state in (MessageState.PENDING, MessageState.IN_PROGRESS):
+ node.mark_error()
+ cancelled_nodes.append(self._ui_target(node))
+ elif (
+ node.state is MessageState.ERROR
+ and active_claim is not None
+ and active_claim.node.node_id == node_id
+ ):
+ cancelled_nodes.append(self._ui_target(node))
+
+ removed_entire_tree = branch_root_id == self.root_id
+ self._graph.remove_branch(branch_root_id)
+ cancellation = TreeCancellation(
+ nodes=tuple(cancelled_nodes),
+ active_claim=active_claim,
+ queue_update=self._queue_entries() if queue_changed else None,
+ )
+ return TreeBranchRemoval(
+ cancellation=cancellation,
+ message_ids=frozenset(message_ids),
+ removed_entire_tree=removed_entire_tree,
+ )
- def put_queue_unlocked(self, node_id: str) -> None:
- self._queue.put_nowait(node_id)
+ async def record_session(
+ self, claim_id: str, session_id: str
+ ) -> TreeSnapshot | None:
+ """Record a real CLI session only for the currently active claim."""
+ async with self._lock:
+ if (
+ self._active is None
+ or self._active.claim.claim_id != claim_id
+ or self._active.cancellation_requested
+ ):
+ return None
+ node = self._graph.get_node(self._active.claim.node.node_id)
+ if node is None or node.state is not MessageState.IN_PROGRESS:
+ return None
+ node.update_state(MessageState.IN_PROGRESS, session_id=session_id)
+ return self._graph.snapshot()
+
+ async def complete_claim(
+ self, claim_id: str, session_id: str | None
+ ) -> TreeSnapshot | None:
+ """Mark the currently active claim complete."""
+ async with self._lock:
+ if (
+ self._active is None
+ or self._active.claim.claim_id != claim_id
+ or self._active.cancellation_requested
+ ):
+ return None
+ node = self._graph.get_node(self._active.claim.node.node_id)
+ if node is None or node.state not in (
+ MessageState.IN_PROGRESS,
+ MessageState.ERROR,
+ ):
+ return None
+ node.update_state(MessageState.COMPLETED, session_id=session_id)
+ return self._graph.snapshot()
+
+ async def fail_claim(
+ self,
+ claim_id: str,
+ *,
+ propagate: bool,
+ ) -> FailureResult:
+ """Atomically fail the active claim and its pending descendants."""
+ async with self._lock:
+ if (
+ self._active is None
+ or self._active.claim.claim_id != claim_id
+ or self._active.cancellation_requested
+ ):
+ return FailureResult(affected=(), queue_update=None, snapshot=None)
+ node = self._graph.get_node(self._active.claim.node.node_id)
+ if node is None:
+ return FailureResult(affected=(), queue_update=None, snapshot=None)
+
+ affected: list[NodeUiTarget] = []
+ queue_changed = False
+ if node.state is not MessageState.COMPLETED:
+ if node.state is not MessageState.ERROR:
+ node.mark_error()
+ affected.append(self._ui_target(node))
+
+ if propagate:
+ for descendant_id in self._graph.get_descendants(node.node_id)[1:]:
+ child = self._graph.get_node(descendant_id)
+ if child is None or child.state is not MessageState.PENDING:
+ continue
+ child.mark_error()
+ queue_changed = (
+ self._queue.remove(child.node_id) or queue_changed
+ )
+ affected.append(self._ui_target(child))
+
+ return FailureResult(
+ affected=tuple(affected),
+ queue_update=self._queue_entries() if queue_changed else None,
+ snapshot=self._graph.snapshot(),
+ )
- def set_current_task(self, task: asyncio.Task | None) -> None:
- self._current_task = task
+ async def resolve_reply(self, reference_id: str) -> ReplyTarget | None:
+ """Resolve a node/status reference without exposing the mutable graph."""
+ async with self._lock:
+ node = self._graph.get_node(reference_id)
+ if node is None:
+ node = self._graph.find_node_by_status_message(reference_id)
+ if node is None:
+ return None
+ return ReplyTarget(
+ node_id=node.node_id,
+ queue_position=(self._queue.qsize() + 1)
+ if self._active is not None
+ else None,
+ )
- @property
- def current_task(self) -> asyncio.Task | None:
- return self._current_task
-
- def cancel_current_task(self) -> asyncio.Task | None:
- if self._current_task and not self._current_task.done():
- self._current_task.cancel()
- return self._current_task
- return None
-
- def set_node_error_sync(self, node: MessageNode, error_message: str) -> None:
- node.mark_error(error_message)
-
- def drain_queue_and_mark_cancelled(
- self, error_message: str = "Cancelled by user"
- ) -> list[MessageNode]:
- nodes: list[MessageNode] = []
- for node_id in self._queue.drain():
+ async def node_view(self, node_id: str) -> NodeView | None:
+ """Return a copied node read model."""
+ async with self._lock:
node = self._graph.get_node(node_id)
- if node:
- self.set_node_error_sync(node, error_message)
- nodes.append(node)
- return nodes
-
- def reset_processing_state(self) -> None:
- self._is_processing = False
- self._current_node_id = None
-
- def all_nodes(self) -> list[MessageNode]:
- return self._graph.all_nodes()
-
- def has_node(self, node_id: str) -> bool:
- return self._graph.has_node(node_id)
-
- def find_node_by_status_message(self, status_msg_id: str) -> MessageNode | None:
- return self._graph.find_node_by_status_message(status_msg_id)
-
- def get_descendants(self, node_id: str) -> list[str]:
- return self._graph.get_descendants(node_id)
+ if node is None:
+ return None
+ return NodeView(
+ identity=self.identity,
+ node_id=node.node_id,
+ state=node.state,
+ parent_id=node.parent_id,
+ session_id=node.session_id,
+ )
- def remove_branch(self, branch_root_id: str) -> list[MessageNode]:
- return self._graph.remove_branch(branch_root_id)
+ async def snapshot(self) -> TreeSnapshot:
+ """Capture a detached persistence snapshot under the aggregate lock."""
+ async with self._lock:
+ return self._graph.snapshot()
- def snapshot(self) -> TreeSnapshot:
- return self._graph.snapshot()
+ async def message_ids_for_chat(self, platform: str, chat_id: str) -> set[str]:
+ """Copy message IDs belonging to one platform chat."""
+ async with self._lock:
+ if self.identity.scope.platform != str(platform) or (
+ self.identity.scope.chat_id != str(chat_id)
+ ):
+ return set()
+ message_ids: set[str] = set()
+ for node in self._graph.all_nodes():
+ message_ids.add(node.node_id)
+ if node.status_message_id:
+ message_ids.add(str(node.status_message_id))
+ return message_ids
@classmethod
def from_snapshot(cls, snapshot: TreeSnapshot) -> MessageTree:
+ """Restore and reconcile interrupted nodes before publishing the tree."""
graph = MessageTreeGraph.from_snapshot(snapshot)
- return cls(graph.get_root(), graph=graph)
+ tree = cls(graph.get_root(), graph=graph)
+ stale_targets: list[NodeUiTarget] = []
+ for node in graph.all_nodes():
+ if node.state in (MessageState.PENDING, MessageState.IN_PROGRESS):
+ stale_targets.append(tree._ui_target(node))
+ node.mark_error()
+ tree._restored_stale_targets = tuple(stale_targets)
+ tree._restored_snapshot = graph.snapshot()
+ return tree
+
+
+__all__ = ["MessageTree"]
diff --git a/src/free_claude_code/messaging/trees/snapshot.py b/src/free_claude_code/messaging/trees/snapshot.py
index 135dbaf6..fa4b0e3a 100644
--- a/src/free_claude_code/messaging/trees/snapshot.py
+++ b/src/free_claude_code/messaging/trees/snapshot.py
@@ -1,22 +1,36 @@
"""Serializable messaging conversation snapshots."""
from dataclasses import dataclass, field
-from datetime import datetime
from typing import Any
-from ..models import IncomingMessage
+from loguru import logger
+
+from ..models import MessageScope
+from .identity import TreeIdentity
from .node import MessageNode, MessageState
@dataclass(frozen=True)
class TreeSnapshot:
- """Persisted representation of one conversation tree."""
+ """Detached persisted representation of one conversation tree."""
+ scope: MessageScope
root_id: str
nodes: dict[str, dict[str, Any]]
+ @property
+ def identity(self) -> TreeIdentity:
+ return TreeIdentity(scope=self.scope, root_id=self.root_id)
+
def to_json(self) -> dict[str, Any]:
- return {"root_id": self.root_id, "nodes": dict(self.nodes)}
+ return {
+ "scope": {
+ "platform": self.scope.platform,
+ "chat_id": self.scope.chat_id,
+ },
+ "root_id": self.root_id,
+ "nodes": dict(self.nodes),
+ }
@classmethod
def from_json(cls, data: Any) -> TreeSnapshot | None:
@@ -26,7 +40,24 @@ class TreeSnapshot:
nodes = data.get("nodes")
if root_id is None or not isinstance(nodes, dict):
return None
- return cls(root_id=str(root_id), nodes=dict(nodes))
+ normalized_root_id = str(root_id)
+ scope_data = data.get("scope")
+ scope: MessageScope | None = None
+ if isinstance(scope_data, dict):
+ platform = scope_data.get("platform")
+ chat_id = scope_data.get("chat_id")
+ if platform is not None and chat_id is not None:
+ scope = MessageScope(platform=str(platform), chat_id=str(chat_id))
+ if scope is None:
+ scope = _legacy_scope(normalized_root_id, nodes)
+ if scope is None:
+ logger.warning(
+ "Skipping messaging tree snapshot without recoverable scope: "
+ "root_id={}",
+ normalized_root_id,
+ )
+ return None
+ return cls(scope=scope, root_id=normalized_root_id, nodes=dict(nodes))
def lookup_ids(self) -> set[str]:
lookup_ids: set[str] = set()
@@ -45,104 +76,121 @@ class TreeSnapshot:
@dataclass(frozen=True)
class ConversationSnapshot:
- """Persisted conversation trees plus derived lookup helpers."""
+ """Detached persisted conversation trees keyed by customer identity."""
- trees: dict[str, TreeSnapshot] = field(default_factory=dict)
+ trees: dict[TreeIdentity, TreeSnapshot] = field(default_factory=dict)
@property
def is_empty(self) -> bool:
return not self.trees
def to_json(self) -> dict[str, Any]:
- return {
- "trees": {
- root_id: tree_snapshot.to_json()
- for root_id, tree_snapshot in self.trees.items()
- }
- }
+ return {"trees": [tree.to_json() for tree in self.trees.values()]}
@classmethod
def from_json(cls, data: Any) -> ConversationSnapshot:
if not isinstance(data, dict):
return cls()
- raw_trees = data.get("trees", {})
- if not isinstance(raw_trees, dict):
+ raw_trees = data.get("trees", [])
+ if isinstance(raw_trees, dict):
+ candidates = raw_trees.values()
+ elif isinstance(raw_trees, list):
+ candidates = raw_trees
+ else:
return cls()
- trees: dict[str, TreeSnapshot] = {}
- for raw_root_id, raw_tree in raw_trees.items():
+ trees: dict[TreeIdentity, TreeSnapshot] = {}
+ for raw_tree in candidates:
snapshot = TreeSnapshot.from_json(raw_tree)
if snapshot is None:
continue
- root_id = str(raw_root_id) if raw_root_id is not None else snapshot.root_id
- trees[root_id] = snapshot
+ trees[snapshot.identity] = snapshot
return cls(trees=trees)
- def derive_node_to_tree(self) -> dict[str, str]:
- mapping: dict[str, str] = {}
- for root_id, tree_snapshot in self.trees.items():
- for lookup_id in tree_snapshot.lookup_ids():
- mapping[lookup_id] = root_id
- return mapping
+ def get_tree(self, identity: TreeIdentity) -> TreeSnapshot | None:
+ return self.trees.get(identity)
def with_tree(self, tree_snapshot: TreeSnapshot) -> ConversationSnapshot:
trees = dict(self.trees)
- trees[tree_snapshot.root_id] = tree_snapshot
+ trees[tree_snapshot.identity] = tree_snapshot
return ConversationSnapshot(trees=trees)
- def without_tree(self, root_id: str) -> ConversationSnapshot:
+ def without_tree(self, identity: TreeIdentity) -> ConversationSnapshot:
trees = dict(self.trees)
- trees.pop(root_id, None)
+ trees.pop(identity, None)
return ConversationSnapshot(trees=trees)
+def _legacy_scope(
+ root_id: str,
+ nodes: dict[str, Any],
+) -> MessageScope | None:
+ """Derive scope from pre-scope snapshots without retaining a runtime shim."""
+ root = nodes.get(root_id)
+ if not isinstance(root, dict):
+ root = next(
+ (
+ node
+ for node in nodes.values()
+ if isinstance(node, dict) and str(node.get("node_id")) == root_id
+ ),
+ None,
+ )
+ if not isinstance(root, dict):
+ return None
+ return node_scope_from_snapshot(root)
+
+
+def node_scope_from_snapshot(data: dict[str, Any]) -> MessageScope | None:
+ """Read the redundant scope carried by legacy node payloads, if present."""
+ incoming = data.get("incoming")
+ if not isinstance(incoming, dict):
+ return None
+ platform = incoming.get("platform")
+ chat_id = incoming.get("chat_id")
+ if platform is None or chat_id is None:
+ return None
+ return MessageScope(platform=str(platform), chat_id=str(chat_id))
+
+
def node_to_snapshot(node: MessageNode) -> dict[str, Any]:
return {
"node_id": node.node_id,
- "incoming": {
- "text": node.incoming.text,
- "chat_id": node.incoming.chat_id,
- "user_id": node.incoming.user_id,
- "message_id": node.incoming.message_id,
- "platform": node.incoming.platform,
- "reply_to_message_id": node.incoming.reply_to_message_id,
- "message_thread_id": node.incoming.message_thread_id,
- "username": node.incoming.username,
- },
"status_message_id": node.status_message_id,
"state": node.state.value,
"parent_id": node.parent_id,
"session_id": node.session_id,
- "children_ids": list(node.children_ids),
- "created_at": node.created_at.isoformat(),
- "completed_at": node.completed_at.isoformat() if node.completed_at else None,
- "error_message": node.error_message,
}
-def node_from_snapshot(data: dict[str, Any]) -> MessageNode:
- incoming_data = data["incoming"]
- incoming = IncomingMessage(
- text=incoming_data["text"],
- chat_id=incoming_data["chat_id"],
- user_id=incoming_data["user_id"],
- message_id=incoming_data["message_id"],
- platform=incoming_data["platform"],
- reply_to_message_id=incoming_data.get("reply_to_message_id"),
- message_thread_id=incoming_data.get("message_thread_id"),
- username=incoming_data.get("username"),
- )
+def node_from_snapshot(data: dict[str, Any], scope: MessageScope) -> MessageNode:
return MessageNode(
- node_id=data["node_id"],
- incoming=incoming,
- status_message_id=data["status_message_id"],
+ node_id=_required_id(data.get("node_id"), "node_id"),
+ scope=scope,
+ prompt="",
+ status_message_id=_required_id(
+ data.get("status_message_id"),
+ "status_message_id",
+ ),
state=MessageState(data["state"]),
- parent_id=data.get("parent_id"),
- session_id=data.get("session_id"),
- children_ids=list(data.get("children_ids", [])),
- created_at=datetime.fromisoformat(data["created_at"]),
- completed_at=datetime.fromisoformat(data["completed_at"])
- if data.get("completed_at")
- else None,
- error_message=data.get("error_message"),
+ parent_id=_optional_id(data.get("parent_id"), "parent_id"),
+ session_id=_optional_id(data.get("session_id"), "session_id"),
)
+
+
+def _required_id(value: Any, field_name: str) -> str:
+ normalized = _optional_id(value, field_name)
+ if normalized is None:
+ raise ValueError(f"Tree snapshot {field_name} is required")
+ return normalized
+
+
+def _optional_id(value: Any, field_name: str) -> str | None:
+ if value is None:
+ return None
+ if isinstance(value, bool) or not isinstance(value, str | int):
+ raise ValueError(f"Tree snapshot {field_name} must be a string or integer")
+ normalized = str(value)
+ if not normalized:
+ raise ValueError(f"Tree snapshot {field_name} cannot be empty")
+ return normalized
diff --git a/src/free_claude_code/messaging/trees/transitions.py b/src/free_claude_code/messaging/trees/transitions.py
new file mode 100644
index 00000000..747c4495
--- /dev/null
+++ b/src/free_claude_code/messaging/trees/transitions.py
@@ -0,0 +1,161 @@
+"""Detached transition values crossing the messaging tree ownership boundary."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+from ..models import MessageScope
+from .identity import TreeIdentity
+from .node import MessageState
+from .snapshot import TreeSnapshot
+
+
+class CancellationUiOwner(Enum):
+ """Component responsible for the final user-visible cancellation edit."""
+
+ RUNNER = "runner"
+ WORKFLOW = "workflow"
+
+
+class CancellationReason(Enum):
+ """Why a running messaging claim was cancelled."""
+
+ STOP = "stop"
+
+
+@dataclass(frozen=True, slots=True)
+class NodeUiTarget:
+ """Copied node coordinates needed for an external UI effect."""
+
+ scope: MessageScope
+ node_id: str
+ status_message_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class NodeClaim:
+ """Exclusive permission to execute one node in a conversation tree."""
+
+ identity: TreeIdentity
+ claim_id: str
+ node: NodeUiTarget
+ prompt: str
+ parent_session_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class QueueEntry:
+ """One immutable queue-position update."""
+
+ node: NodeUiTarget
+ position: int
+
+
+@dataclass(frozen=True, slots=True)
+class QueueDecision:
+ """Atomic result of admitting a node to a tree."""
+
+ claim: NodeClaim | None
+ position: int | None
+ snapshot: TreeSnapshot | None
+
+ @property
+ def accepted(self) -> bool:
+ return self.snapshot is not None
+
+
+@dataclass(frozen=True, slots=True)
+class CompletionResult:
+ """Atomic result of releasing a claim and selecting its successor."""
+
+ next_claim: NodeClaim | None
+ queue: tuple[QueueEntry, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class CancellationEffect:
+ """Copied cancellation fact for the UI layer."""
+
+ node: NodeUiTarget
+ ui_owner: CancellationUiOwner
+
+
+@dataclass(frozen=True, slots=True)
+class TreeCancellation:
+ """Single-tree cancellation transition consumed by the manager."""
+
+ nodes: tuple[NodeUiTarget, ...]
+ active_claim: NodeClaim | None
+ queue_update: tuple[QueueEntry, ...] | None
+
+
+@dataclass(frozen=True, slots=True)
+class CancellationResult:
+ """External effects and persistence snapshots from a cancellation request."""
+
+ effects: tuple[CancellationEffect, ...] = ()
+ snapshots: tuple[TreeSnapshot, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class TreeBranchRemoval:
+ """Single-tree atomic cancellation and graph-removal transition."""
+
+ cancellation: TreeCancellation
+ message_ids: frozenset[str]
+ removed_entire_tree: bool
+
+
+@dataclass(frozen=True, slots=True)
+class BranchRemovalResult:
+ """Manager result for a branch clear."""
+
+ cancellation: CancellationResult
+ removed_tree_identity: TreeIdentity | None
+ message_ids: frozenset[str]
+
+
+@dataclass(frozen=True, slots=True)
+class ReplyTarget:
+ """Resolved reply destination and advisory position before admission."""
+
+ node_id: str
+ queue_position: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class NodeView:
+ """Immutable read model for diagnostics, tests, and smoke assertions."""
+
+ identity: TreeIdentity
+ node_id: str
+ state: MessageState
+ parent_id: str | None
+ session_id: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class FailureResult:
+ """Atomic node failure plus copied child UI effects."""
+
+ affected: tuple[NodeUiTarget, ...]
+ queue_update: tuple[QueueEntry, ...] | None
+ snapshot: TreeSnapshot | None
+
+
+__all__ = [
+ "BranchRemovalResult",
+ "CancellationEffect",
+ "CancellationReason",
+ "CancellationResult",
+ "CancellationUiOwner",
+ "CompletionResult",
+ "FailureResult",
+ "NodeClaim",
+ "NodeUiTarget",
+ "NodeView",
+ "QueueDecision",
+ "QueueEntry",
+ "ReplyTarget",
+ "TreeBranchRemoval",
+ "TreeCancellation",
+]
diff --git a/src/free_claude_code/messaging/turn_intake.py b/src/free_claude_code/messaging/turn_intake.py
index ea256ee4..fd5c35a0 100644
--- a/src/free_claude_code/messaging/turn_intake.py
+++ b/src/free_claude_code/messaging/turn_intake.py
@@ -13,11 +13,11 @@ from .command_dispatcher import (
message_kind_for_command,
parse_command_base,
)
-from .models import IncomingMessage
+from .models import IncomingMessage, MessageScope
from .platforms.ports import OutboundMessenger
from .safe_diagnostics import format_exception_for_log
from .session import SessionStore
-from .trees import MessageNode, MessageState, MessageTree, TreeQueueManager
+from .trees import NodeClaim, QueueDecision, QueueEntry, ReplyTarget
class MessagingTurnIntake:
@@ -30,8 +30,11 @@ class MessagingTurnIntake:
outbound: OutboundMessenger,
session_store: SessionStore,
command_context: MessagingCommandContext,
- get_tree_queue: Callable[[], TreeQueueManager],
- process_node: Callable[[str, MessageNode], Awaitable[None]],
+ resolve_reply: Callable[[MessageScope, str], Awaitable[ReplyTarget | None]],
+ admit_turn: Callable[
+ [IncomingMessage, str, str | None, int],
+ Awaitable[QueueDecision | 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],
@@ -41,14 +44,19 @@ class MessagingTurnIntake:
self.outbound = outbound
self.session_store = session_store
self._command_context = command_context
- self._get_tree_queue = get_tree_queue
- self._process_node = process_node
+ self._resolve_reply = resolve_reply
+ self._admit_turn = admit_turn
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:
+ async def handle_message(
+ self,
+ incoming: IncomingMessage,
+ *,
+ admission_epoch: int,
+ ) -> None:
"""
Handle an inbound platform message and queue it if it is a user prompt.
"""
@@ -78,25 +86,18 @@ class MessagingTurnIntake:
if any(text.startswith(p) for p in STATUS_MESSAGE_PREFIXES):
return
- parent_node_id = None
- tree = None
- tree_queue = self._get_tree_queue()
+ reply_target: ReplyTarget | None = None
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
+ reply_target = await self._resolve_reply(incoming.scope, reply_id)
+ if reply_target is not None:
+ logger.info(
+ "Found tree for reply, parent node: {}", reply_target.node_id
+ )
node_id = incoming.message_id
- status_text = self._get_initial_status(tree, parent_node_id)
+ status_text = self._get_initial_status(reply_target)
if incoming.status_message_id:
status_msg_id = incoming.status_message_id
await self.outbound.queue_edit_message(
@@ -117,34 +118,28 @@ class MessagingTurnIntake:
self._record_outgoing_message(
incoming.platform, incoming.chat_id, status_msg_id, "status"
)
+ if status_msg_id is None:
+ return
- 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)
- 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)
-
- if tree:
- self.session_store.save_tree_snapshot(tree.snapshot())
-
- was_queued = await tree_queue.enqueue(
- node_id=node_id,
- processor=self._process_node,
+ decision = await self._admit_turn(
+ incoming,
+ status_msg_id,
+ reply_target.node_id if reply_target is not None else None,
+ admission_epoch,
)
+ if decision is None:
+ logger.info(
+ "Discarded messaging admission invalidated by global stop/clear for node {}",
+ node_id,
+ )
+ await self._discard_rejected_status(incoming, status_msg_id)
+ return
+ if not decision.accepted:
+ logger.debug("Ignored duplicate messaging admission for node {}", node_id)
+ await self._discard_rejected_status(incoming, status_msg_id)
+ return
- if was_queued and status_msg_id:
- queue_size = tree_queue.get_queue_size(node_id)
+ if decision.position is not None and status_msg_id:
trace_event(
stage="routing",
event="turn.queued",
@@ -152,59 +147,70 @@ class MessagingTurnIntake:
chat_id=incoming.chat_id,
platform_message_id=node_id,
status_message_id=status_msg_id,
- queue_size=queue_size,
+ queue_size=decision.position,
)
await self.outbound.queue_edit_message(
incoming.chat_id,
status_msg_id,
self._format_status(
- "📋", "Queued", f"(position {queue_size}) - waiting..."
+ "📋",
+ "Queued",
+ f"(position {decision.position}) - waiting...",
),
parse_mode=self._get_parse_mode(),
)
- async def update_queue_positions(self, tree: MessageTree) -> None:
- """Refresh queued status messages after a dequeue."""
+ async def _discard_rejected_status(
+ self,
+ incoming: IncomingMessage,
+ status_message_id: str,
+ ) -> None:
+ """Remove the provisional status created for a rejected admission."""
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
- ),
+ await self.outbound.queue_delete_messages(
+ incoming.chat_id,
+ [status_message_id],
+ fire_and_forget=False,
+ )
+ except Exception as exc:
+ logger.debug(
+ "Failed to remove rejected status message: {}",
+ type(exc).__name__,
+ )
+ try:
+ self.session_store.forget_message_ids(
+ incoming.platform,
+ incoming.chat_id,
+ {status_message_id},
+ )
+ except Exception as exc:
+ logger.debug(
+ "Failed to forget rejected status message: {}",
+ type(exc).__name__,
)
- 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
+ async def update_queue_positions(self, queue: tuple[QueueEntry, ...]) -> None:
+ """Refresh queued status messages after a dequeue."""
+ for entry in queue:
self.outbound.fire_and_forget(
self.outbound.queue_edit_message(
- node.incoming.chat_id,
- node.status_message_id,
+ entry.node.scope.chat_id,
+ entry.node.status_message_id,
self._format_status(
- "📋", "Queued", f"(position {position}) - waiting..."
+ "📋",
+ "Queued",
+ f"(position {entry.position}) - waiting...",
),
parse_mode=self._get_parse_mode(),
)
)
- async def mark_node_processing(self, tree: MessageTree, node_id: str) -> None:
+ async def mark_node_processing(self, claim: NodeClaim) -> 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.outbound.fire_and_forget(
self.outbound.queue_edit_message(
- node.incoming.chat_id,
- node.status_message_id,
+ claim.node.scope.chat_id,
+ claim.node.status_message_id,
self._format_status("🔄", "Processing...", None),
parse_mode=self._get_parse_mode(),
)
@@ -212,16 +218,15 @@ class MessagingTurnIntake:
def _get_initial_status(
self,
- tree: object | None,
- parent_node_id: str | None,
+ reply_target: ReplyTarget | 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
+ if reply_target is not None:
+ if reply_target.queue_position is not None:
return self._format_status(
- "📋", "Queued", f"(position {queue_size}) - waiting..."
+ "📋",
+ "Queued",
+ f"(position {reply_target.queue_position}) - waiting...",
)
return self._format_status("🔄", "Continuing conversation...", None)
diff --git a/src/free_claude_code/messaging/voice.py b/src/free_claude_code/messaging/voice.py
index 908c1588..d6eb72ba 100644
--- a/src/free_claude_code/messaging/voice.py
+++ b/src/free_claude_code/messaging/voice.py
@@ -4,6 +4,8 @@ import asyncio
from pathlib import Path
from typing import Protocol
+from .models import MessageScope
+
class Transcriber(Protocol):
"""Consumer-owned voice transcription boundary."""
@@ -17,34 +19,36 @@ class PendingVoiceRegistry:
"""Track voice notes that are still waiting on transcription."""
def __init__(self) -> None:
- self._pending: dict[tuple[str, str], tuple[str, str]] = {}
+ self._pending: dict[tuple[MessageScope, str], tuple[str, str]] = {}
self._lock = asyncio.Lock()
async def register(
- self, chat_id: str, voice_msg_id: str, status_msg_id: str
+ self, scope: MessageScope, voice_msg_id: str, status_msg_id: str
) -> None:
async with self._lock:
entry = (voice_msg_id, status_msg_id)
- self._pending[(chat_id, voice_msg_id)] = entry
- self._pending[(chat_id, status_msg_id)] = entry
+ self._pending[(scope, voice_msg_id)] = entry
+ self._pending[(scope, status_msg_id)] = entry
- async def cancel(self, chat_id: str, reply_id: str) -> tuple[str, str] | None:
+ async def cancel(
+ self, scope: MessageScope, reply_id: str
+ ) -> tuple[str, str] | None:
async with self._lock:
- entry = self._pending.pop((chat_id, reply_id), None)
+ entry = self._pending.pop((scope, reply_id), None)
if entry is None:
return None
voice_msg_id, status_msg_id = entry
- self._pending.pop((chat_id, voice_msg_id), None)
- self._pending.pop((chat_id, status_msg_id), None)
+ self._pending.pop((scope, voice_msg_id), None)
+ self._pending.pop((scope, status_msg_id), None)
return entry
- async def is_pending(self, chat_id: str, voice_msg_id: str) -> bool:
+ async def is_pending(self, scope: MessageScope, voice_msg_id: str) -> bool:
async with self._lock:
- return (chat_id, voice_msg_id) in self._pending
+ return (scope, voice_msg_id) in self._pending
async def complete(
- self, chat_id: str, voice_msg_id: str, status_msg_id: str
+ self, scope: MessageScope, voice_msg_id: str, status_msg_id: str
) -> None:
async with self._lock:
- self._pending.pop((chat_id, voice_msg_id), None)
- self._pending.pop((chat_id, status_msg_id), None)
+ self._pending.pop((scope, voice_msg_id), None)
+ self._pending.pop((scope, status_msg_id), None)
diff --git a/src/free_claude_code/messaging/workflow.py b/src/free_claude_code/messaging/workflow.py
index 2b0eb583..ad2f6b2f 100644
--- a/src/free_claude_code/messaging/workflow.py
+++ b/src/free_claude_code/messaging/workflow.py
@@ -1,11 +1,13 @@
"""Messaging workflow coordinator for Discord and Telegram prompts."""
+import asyncio
+
from loguru import logger
from free_claude_code.core.trace import trace_event
from .managed_protocols import ManagedClaudeSessionManagerProtocol
-from .models import IncomingMessage
+from .models import IncomingMessage, MessageScope
from .node_runner import MessagingNodeRunner
from .platforms.ports import OutboundMessenger, VoiceCancellation
from .rendering.profiles import build_rendering_profile
@@ -13,22 +15,22 @@ from .safe_diagnostics import format_exception_for_log
from .session import SessionStore
from .transcript import RenderCtx
from .trees import (
+ BranchRemovalResult,
CancellationReason,
+ CancellationResult,
CancellationUiOwner,
- CancelledNode,
- MessageTree,
+ ConversationSnapshot,
+ FailureResult,
+ NodeUiTarget,
+ QueueDecision,
+ ReplyTarget,
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.
- """
+ """Own messaging state transitions and their external side effects."""
def __init__(
self,
@@ -40,19 +42,21 @@ class MessagingWorkflow:
voice_cancellation: VoiceCancellation | None = None,
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,
- ):
+ ) -> None:
self.platform_name = platform_name or "messaging"
self.outbound = outbound
self.voice_cancellation = voice_cancellation
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(self.platform_name)
+ self._state_lock = asyncio.Lock()
+ self._admission_epoch = 0
+ self._pending_restored_status_targets: tuple[NodeUiTarget, ...] = ()
+ self._tree_queue: TreeQueueManager
self.node_runner = MessagingNodeRunner(
platform_name=self.platform_name,
outbound=outbound,
@@ -73,21 +77,31 @@ class MessagingWorkflow:
outbound=outbound,
session_store=session_store,
command_context=self,
- get_tree_queue=lambda: self._tree_queue,
- process_node=self.node_runner.process_node,
+ resolve_reply=self.resolve_reply,
+ admit_turn=self._admit_turn_if_current,
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()
+ self._tree_queue = self._build_tree_queue()
- 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 _build_tree_queue(
+ self, snapshot: ConversationSnapshot | None = None
+ ) -> TreeQueueManager:
+ if snapshot is None:
+ return TreeQueueManager(
+ self.node_runner.process_node,
+ queue_update_callback=self.turn_intake.update_queue_positions,
+ node_started_callback=self.turn_intake.mark_node_processing,
+ unexpected_failure_callback=self._apply_unexpected_failure,
+ )
+ return TreeQueueManager.from_snapshot(
+ snapshot,
+ self.node_runner.process_node,
+ queue_update_callback=self.turn_intake.update_queue_positions,
+ node_started_callback=self.turn_intake.mark_node_processing,
+ unexpected_failure_callback=self._apply_unexpected_failure,
)
def format_status(self, emoji: str, label: str, suffix: str | None = None) -> str:
@@ -104,32 +118,51 @@ class MessagingWorkflow:
@property
def tree_queue(self) -> TreeQueueManager:
- """Accessor for the current tree queue manager."""
+ """Expose the manager facade for diagnostics and smoke tests."""
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()
-
def restore(self) -> None:
- """Restore persisted conversations into this workflow's owned queue."""
+ """Restore and reconcile persisted conversations before platform start."""
snapshot = self.session_store.load_conversation_snapshot()
if snapshot.is_empty:
return
logger.info("Restoring {} conversation trees...", len(snapshot.trees))
- self.replace_tree_queue(TreeQueueManager.from_snapshot(snapshot))
- if self.tree_queue.cleanup_stale_nodes() > 0:
- self.session_store.save_conversation_snapshot(self.tree_queue.snapshot())
+ self._tree_queue = self._build_tree_queue(snapshot)
+ normalized = self._tree_queue.restored_snapshot
+ if normalized is not None and normalized != snapshot:
+ self.session_store.save_conversation_snapshot(normalized)
+ self._pending_restored_status_targets = self._tree_queue.restored_stale_targets
+
+ async def repair_restored_statuses(self) -> None:
+ """Replace stale queued/processing UI after delivery becomes available."""
+ targets = self._pending_restored_status_targets
+ self._pending_restored_status_targets = ()
+ for target in targets:
+ if self.platform_name != "messaging" and (
+ target.scope.platform != self.platform_name
+ ):
+ continue
+ try:
+ await self.outbound.queue_edit_message(
+ target.scope.chat_id,
+ target.status_message_id,
+ self.format_status("❌", "Interrupted by server restart"),
+ parse_mode=self._parse_mode(),
+ fire_and_forget=False,
+ )
+ except Exception as exc:
+ logger.debug(
+ "Failed to repair restored status for node {}: {}",
+ target.node_id,
+ type(exc).__name__,
+ )
def close(self) -> None:
"""Flush pending session persistence before runtime shutdown."""
self.session_store.flush_pending_save()
async def handle_message(self, incoming: IncomingMessage) -> None:
- """
- Main entry point for handling an incoming platform message.
- """
+ """Handle one platform message."""
trace_event(
stage="ingress",
event="turn.received",
@@ -137,47 +170,157 @@ class MessagingWorkflow:
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),
+ thread_id=incoming.message_thread_id,
message_text=incoming.text or "",
)
-
with logger.contextualize(
- chat_id=incoming.chat_id, node_id=incoming.message_id
+ chat_id=incoming.chat_id,
+ node_id=incoming.message_id,
):
- await self.turn_intake.handle_message(incoming)
+ async with self._state_lock:
+ admission_epoch = self._admission_epoch
+ await self.turn_intake.handle_message(
+ incoming,
+ admission_epoch=admission_epoch,
+ )
- 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 resolve_reply(
+ self,
+ scope: MessageScope,
+ reference_id: str,
+ ) -> ReplyTarget | None:
+ return await self._tree_queue.resolve_reply(scope, reference_id)
- 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 _admit_turn_if_current(
+ self,
+ incoming: IncomingMessage,
+ status_message_id: str,
+ parent_node_id: str | None,
+ admission_epoch: int,
+ ) -> QueueDecision | None:
+ async with self._state_lock:
+ if admission_epoch != self._admission_epoch:
+ return None
+ return await self._admit_locked(
+ incoming,
+ status_message_id,
+ parent_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(
- reason=CancellationReason.STOP
+ async def _admit_locked(
+ self,
+ incoming: IncomingMessage,
+ status_message_id: str,
+ parent_node_id: str | None,
+ ) -> QueueDecision:
+ """Admit while the workflow caller owns the state transaction lock."""
+ decision = await self._tree_queue.admit(
+ incoming,
+ status_message_id,
+ parent_node_id=parent_node_id,
)
- logger.info(f"Cancelled {len(cancelled_nodes)} nodes")
+ if decision.snapshot is not None:
+ self.session_store.save_tree_snapshot(decision.snapshot)
+ return decision
- logger.info("Stopping all CLI sessions...")
- await self.cli_manager.stop_all()
+ async def resolve_node_id(
+ self,
+ scope: MessageScope,
+ reference_id: str,
+ ) -> str | None:
+ return await self._tree_queue.resolve_node_id(scope, reference_id)
- self.update_cancelled_nodes_ui(cancelled_nodes)
- return len(cancelled_nodes)
+ def get_tree_count(self) -> int:
+ return self._tree_queue.get_tree_count()
- async def stop_task(self, node_id: str) -> int:
- """Stop a single queued or in-progress task node."""
- cancelled_nodes = await self.tree_queue.cancel_node(
- node_id,
- reason=CancellationReason.STOP,
- )
- self.update_cancelled_nodes_ui(cancelled_nodes)
- return len(cancelled_nodes)
+ async def stop_all_tasks(self) -> int:
+ """Stop every pending and active messaging task."""
+ async with self._state_lock:
+ self._admission_epoch += 1
+ logger.info("Cancelling tree queue tasks...")
+ result = await self._tree_queue.cancel_all(reason=CancellationReason.STOP)
+ logger.info("Cancelled {} nodes", len(result.effects))
+ self._apply_cancellation_result(result)
+ logger.info("Stopping all CLI sessions...")
+ await self.cli_manager.stop_all()
+ return len(result.effects)
+
+ async def stop_task(self, scope: MessageScope, node_id: str) -> int:
+ """Stop one queued or active task."""
+ async with self._state_lock:
+ result = await self._tree_queue.cancel_node(
+ scope,
+ node_id,
+ reason=CancellationReason.STOP,
+ )
+ self._apply_cancellation_result(result)
+ return len(result.effects)
+
+ async def clear_branch(
+ self,
+ scope: MessageScope,
+ node_id: str,
+ ) -> BranchRemovalResult:
+ """Cancel, detach, and persist a branch before platform deletion."""
+ async with self._state_lock:
+ result = await self._tree_queue.remove_branch(scope, node_id)
+ self._apply_cancellation_result(result.cancellation)
+ if result.removed_tree_identity is not None:
+ self.session_store.remove_tree_snapshot(result.removed_tree_identity)
+ return result
+
+ async def clear_all_state(self, platform: str, chat_id: str) -> frozenset[str]:
+ """Clear FCC state atomically with respect to later turn admission."""
+ async with self._state_lock:
+ message_ids: set[str] = set()
+ try:
+ message_ids.update(
+ str(message_id)
+ for message_id in self.session_store.get_message_ids_for_chat(
+ platform,
+ chat_id,
+ )
+ if message_id is not None
+ )
+ except Exception as exc:
+ logger.debug(
+ "Failed to read message log for /clear: {}", type(exc).__name__
+ )
+
+ message_ids.update(
+ await self._tree_queue.get_message_ids_for_chat(platform, chat_id)
+ )
+ # All fallible/cancellable reads precede the commit boundary. Once
+ # the epoch advances, the following synchronous wipe and the
+ # manager's cancellation-safe detach complete as one-way work.
+ self._admission_epoch += 1
+ try:
+ self.session_store.clear_all()
+ except Exception as exc:
+ logger.warning("Failed to clear session store: {}", type(exc).__name__)
+
+ result = await self._tree_queue.clear_all(reason=CancellationReason.STOP)
+ # A runner may terminalize during task draining after the early
+ # store clear. The detached manager now rejects later writes; clear
+ # this final pre-detach snapshot without erasing newer message logs.
+ self.session_store.clear_conversation_snapshot()
+ self._apply_cancellation_result(result)
+ await self.cli_manager.stop_all()
+ return frozenset(message_ids)
+
+ def forget_message_ids(
+ self,
+ platform: str,
+ chat_id: str,
+ message_ids: set[str],
+ ) -> None:
+ try:
+ self.session_store.forget_message_ids(platform, chat_id, message_ids)
+ except Exception as exc:
+ logger.warning(
+ "Failed to update session store after branch clear: {}",
+ type(exc).__name__,
+ )
def record_outgoing_message(
self,
@@ -186,40 +329,54 @@ class MessagingWorkflow:
msg_id: str | None,
kind: str,
) -> None:
- """Record outgoing message ID for /clear. Best-effort, never raises."""
+ """Record an outgoing message ID for /clear, best effort."""
if not msg_id:
return
try:
self.session_store.record_message_id(
- platform, chat_id, str(msg_id), direction="out", kind=kind
+ platform,
+ chat_id,
+ str(msg_id),
+ direction="out",
+ kind=kind,
)
- except Exception as e:
+ except Exception as exc:
logger.debug(
"Failed to record message_id: {}",
format_exception_for_log(
- e, log_full_message=self._log_messaging_error_details
+ exc,
+ log_full_message=self._log_messaging_error_details,
),
)
- def update_cancelled_nodes_ui(self, nodes: list[CancelledNode]) -> None:
- """Update status messages and persist tree state for cancelled nodes."""
- trees_to_save: dict[str, MessageTree] = {}
- for cancelled in nodes:
- node = cancelled.node
- if cancelled.ui_owner is CancellationUiOwner.WORKFLOW:
+ def _apply_cancellation_result(self, result: CancellationResult) -> None:
+ """Apply detached UI and persistence effects from one transition."""
+ for effect in result.effects:
+ if effect.ui_owner is CancellationUiOwner.WORKFLOW:
self.outbound.fire_and_forget(
self.outbound.queue_edit_message(
- node.incoming.chat_id,
- node.status_message_id,
+ effect.node.scope.chat_id,
+ effect.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 tree in trees_to_save.values():
- self.session_store.save_tree_snapshot(tree.snapshot())
+ for snapshot in result.snapshots:
+ self.session_store.save_tree_snapshot(snapshot)
+
+ def _apply_unexpected_failure(self, result: FailureResult) -> None:
+ """Persist and render a failure that escaped the total node runner."""
+ if result.snapshot is not None:
+ self.session_store.save_tree_snapshot(result.snapshot)
+ for target in result.affected:
+ self.outbound.fire_and_forget(
+ self.outbound.queue_edit_message(
+ target.scope.chat_id,
+ target.status_message_id,
+ self.format_status("💥", "Task Failed"),
+ parse_mode=self._parse_mode(),
+ )
+ )
__all__ = ["MessagingWorkflow"]
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index 5bece33b..041acfb1 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -379,13 +379,13 @@ class ApplicationRuntime:
session_store=session_store,
debug_platform_edits=settings.debug_platform_edits,
debug_subagent_stack=settings.debug_subagent_stack,
- log_raw_messaging_content=settings.log_raw_messaging_content,
log_raw_cli_diagnostics=settings.log_raw_cli_diagnostics,
log_messaging_error_details=settings.log_messaging_error_details,
)
self._messaging_workflow.restore()
components.runtime.on_message(self._messaging_workflow.handle_message)
await components.runtime.start()
+ await self._messaging_workflow.repair_restored_statuses()
logger.info("{} platform started with messaging workflow", components.name)
async def _close_owned_resources(self) -> bool:
diff --git a/tests/contracts/test_import_boundaries.py b/tests/contracts/test_import_boundaries.py
index 0c59ccd2..44f7eaab 100644
--- a/tests/contracts/test_import_boundaries.py
+++ b/tests/contracts/test_import_boundaries.py
@@ -858,6 +858,39 @@ def test_messaging_conversation_state_uses_package_owners() -> None:
)
assert offenders == []
+
+def test_message_tree_mutability_stays_inside_its_owner_package() -> None:
+ repo_root = Path(__file__).resolve().parents[2]
+ messaging_root = repo_root / "src" / "free_claude_code" / "messaging"
+ trees_root = messaging_root / "trees"
+ forbidden = (
+ "free_claude_code.messaging.trees.node",
+ "free_claude_code.messaging.trees.processor",
+ "free_claude_code.messaging.trees.repository",
+ "free_claude_code.messaging.trees.runtime",
+ )
+
+ offenders: list[str] = []
+ for path in messaging_root.rglob("*.py"):
+ if trees_root in path.parents:
+ continue
+ offenders.extend(
+ f"{path.relative_to(repo_root)}: {imported}"
+ for imported in _imports_from(path, repo_root)
+ if imported is not None and _is_forbidden(imported, forbidden)
+ )
+
+ assert sorted(offenders) == []
+
+ facade = (trees_root / "__init__.py").read_text(encoding="utf-8")
+ for mutable_owner in {
+ "MessageNode",
+ "MessageTree",
+ "TreeQueueProcessor",
+ "TreeRepository",
+ }:
+ assert f'"{mutable_owner}"' not in facade
+
runtime_text = (
repo_root / "src" / "free_claude_code" / "runtime" / "application.py"
).read_text(encoding="utf-8")
diff --git a/tests/messaging/test_discord_platform.py b/tests/messaging/test_discord_platform.py
index 460ee9c2..17c41a70 100644
--- a/tests/messaging/test_discord_platform.py
+++ b/tests/messaging/test_discord_platform.py
@@ -87,12 +87,9 @@ class TestDiscordInbound:
assert incoming.text == "hello"
assert incoming.chat_id == "123"
- assert incoming.user_id == "456"
assert incoming.message_id == "789"
assert incoming.platform == "discord"
assert incoming.reply_to_message_id == "555"
- assert incoming.username == "User"
- assert incoming.raw_event is msg
@pytest.mark.skipif(not DISCORD_AVAILABLE, reason="discord.py not installed")
@@ -290,7 +287,6 @@ class TestDiscordRuntime:
call = handler.call_args[0][0]
assert call.text == "hello"
assert call.chat_id == "123"
- assert call.user_id == "456"
assert call.message_id == "789"
assert call.platform == "discord"
diff --git a/tests/messaging/test_handler.py b/tests/messaging/test_handler.py
index a53ccf24..68fb2819 100644
--- a/tests/messaging/test_handler.py
+++ b/tests/messaging/test_handler.py
@@ -1,99 +1,124 @@
import asyncio
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, call, patch
import pytest
-from free_claude_code.messaging.models import IncomingMessage
+from free_claude_code.messaging.models import MessageScope
+from free_claude_code.messaging.session import SessionStore
from free_claude_code.messaging.trees import (
CancellationReason,
+ CancellationResult,
CancellationUiOwner,
- CancelledNode,
- MessageNode,
+ FailureResult,
MessageState,
- MessageTree,
- TreeQueueManager,
+ NodeClaim,
+ NodeUiTarget,
+ QueueEntry,
+ ReplyTarget,
+ TreeIdentity,
+ TreeSnapshot,
)
+from free_claude_code.messaging.trees.transitions import CancellationEffect
from free_claude_code.messaging.workflow import MessagingWorkflow
+_SCOPE = MessageScope(platform="telegram", chat_id="chat_1")
+
+
+async def _event_stream(events):
+ for event in events:
+ await asyncio.sleep(0)
+ yield event
+
+
+def _claim(
+ node_id: str = "node_1",
+ *,
+ prompt: str = "hello",
+ parent_session_id: str | None = None,
+) -> NodeClaim:
+ return NodeClaim(
+ identity=TreeIdentity(scope=_SCOPE, root_id="root_1"),
+ claim_id="claim_1",
+ node=NodeUiTarget(
+ scope=_SCOPE,
+ node_id=node_id,
+ status_message_id="status_1",
+ ),
+ prompt=prompt,
+ parent_session_id=parent_session_id,
+ )
+
+
+def _snapshot(root_id: str = "root_1") -> TreeSnapshot:
+ return TreeSnapshot(scope=_SCOPE, root_id=root_id, nodes={})
+
+
+def _session(events) -> MagicMock:
+ session = MagicMock()
+ session.start_task.return_value = _event_stream(events)
+ return session
+
+
+async def _wait_for_idle(workflow: MessagingWorkflow) -> None:
+ for _ in range(200):
+ if workflow.tree_queue.task_count() == 0:
+ await asyncio.sleep(0)
+ return
+ await asyncio.sleep(0.01)
+ raise AssertionError("messaging workflow did not become idle")
+
@pytest.fixture
def handler(mock_platform, mock_cli_manager, mock_session_store):
+ default_session = _session([{"type": "exit", "code": 0}])
+ mock_cli_manager.get_or_create_session.return_value = (
+ default_session,
+ "session_1",
+ False,
+ )
return MessagingWorkflow(
mock_platform,
mock_cli_manager,
mock_session_store,
+ platform_name="telegram",
voice_cancellation=mock_platform,
)
@pytest.mark.asyncio
-async def test_handle_message_turn_trace_includes_full_message_text(
- mock_platform, mock_cli_manager, mock_session_store, incoming_message_factory
-):
- """turn.received always records the verbatim user message (local debugging)."""
- secret = "user-message-content-visible-in-trace"
- handler = MessagingWorkflow(
- mock_platform,
- mock_cli_manager,
- mock_session_store,
- log_raw_messaging_content=False,
- )
- incoming = incoming_message_factory(text=secret)
- with (
- patch.object(handler.turn_intake, "handle_message", new_callable=AsyncMock),
- patch("free_claude_code.messaging.workflow.trace_event") as trace_mock,
- ):
- await handler.handle_message(incoming)
- kwargs = trace_mock.call_args.kwargs
- assert kwargs["event"] == "turn.received"
- assert kwargs["message_text"] == secret
-
-
-async def test_handle_message_log_raw_messaging_does_not_change_turn_received_shape(
- mock_platform, mock_cli_manager, mock_session_store, incoming_message_factory
+async def test_handle_message_turn_trace_always_includes_full_message_text(
+ mock_platform,
+ mock_cli_manager,
+ mock_session_store,
+ incoming_message_factory,
):
- """LOG_RAW_MESSAGING_CONTENT is adapter-only; ingress TRACE always includes text."""
- text = "visible-either-way"
- handler = MessagingWorkflow(
+ text = "user-message-content-visible-in-trace"
+ workflow = MessagingWorkflow(
mock_platform,
mock_cli_manager,
mock_session_store,
- log_raw_messaging_content=True,
)
incoming = incoming_message_factory(text=text)
with (
- patch.object(handler.turn_intake, "handle_message", new_callable=AsyncMock),
+ patch.object(workflow.turn_intake, "handle_message", new_callable=AsyncMock),
patch("free_claude_code.messaging.workflow.trace_event") as trace_mock,
):
- await handler.handle_message(incoming)
- assert trace_mock.call_args.kwargs["message_text"] == text
-
+ await workflow.handle_message(incoming)
-def test_get_initial_status_new_conversation(handler):
- """New conversation always returns launching message."""
- result = handler.turn_intake._get_initial_status(None, None)
- assert "Launching" in result
-
-
-def test_get_initial_status_reply_tree_busy_queued(handler):
- """Reply to tree when busy returns queued message."""
- mock_queue = MagicMock()
- 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.turn_intake._get_initial_status(MagicMock(), "parent_1")
- assert "Queued" in result
- assert "position 3" in result
+ assert trace_mock.call_args.kwargs["event"] == "turn.received"
+ assert trace_mock.call_args.kwargs["message_text"] == text
-def test_get_initial_status_reply_tree_not_busy_continuing(handler):
- """Reply to tree when not busy returns continuing message."""
- mock_queue = MagicMock()
- mock_queue.is_node_tree_busy.return_value = False
- handler.replace_tree_queue(mock_queue)
- result = handler.turn_intake._get_initial_status(MagicMock(), "parent_1")
- assert "Continuing" in result
+ ("target", "expected"),
+ [
+ (None, "Launching"),
+ (ReplyTarget(node_id="parent", queue_position=None), "Continuing"),
+ (ReplyTarget(node_id="parent", queue_position=3), "position 3"),
+ ],
+)
+def test_initial_status_uses_immutable_reply_advice(handler, target, expected):
+ assert expected in handler.turn_intake._get_initial_status(target)
@pytest.mark.asyncio
@@ -101,14 +126,12 @@ async def test_handle_message_stop_command(
handler, mock_platform, incoming_message_factory
):
incoming = incoming_message_factory(text="/stop")
-
- # Mock stop_all_tasks
handler.stop_all_tasks = AsyncMock(return_value=5)
await handler.handle_message(incoming)
- handler.stop_all_tasks.assert_called_once()
- mock_platform.queue_send_message.assert_called_once_with(
+ handler.stop_all_tasks.assert_awaited_once()
+ mock_platform.queue_send_message.assert_awaited_once_with(
incoming.chat_id,
"⏹ *Stopped\\.* Cancelled 5 pending or active requests\\.",
fire_and_forget=False,
@@ -117,611 +140,608 @@ async def test_handle_message_stop_command(
@pytest.mark.asyncio
-async def test_handle_message_stop_command_reply_stops_only_target_node(
+async def test_reply_stop_resolves_and_stops_only_target(
handler, mock_platform, mock_cli_manager, incoming_message_factory
):
- # Create a tree with a root node and register its status message ID mapping.
- root_incoming = incoming_message_factory(
- text="do something", message_id="root_msg", reply_to_message_id=None
- )
- tree = await handler.tree_queue.create_tree(
- node_id="root_msg",
- incoming=root_incoming,
- status_message_id="status_root",
- )
- handler.tree_queue.register_node("status_root", tree.root_id)
-
- # Reply "/stop" to the status message; should stop only that node.
+ handler.resolve_node_id = AsyncMock(return_value="root_msg")
+ handler.stop_task = AsyncMock(return_value=1)
+ handler.stop_all_tasks = AsyncMock(return_value=999)
incoming = incoming_message_factory(
text="/stop",
message_id="stop_msg",
reply_to_message_id="status_root",
)
- handler.stop_all_tasks = AsyncMock(return_value=999)
-
await handler.handle_message(incoming)
- handler.stop_all_tasks.assert_not_called()
- mock_cli_manager.stop_all.assert_not_called()
- assert tree.get_node("root_msg").state == MessageState.ERROR
- mock_platform.queue_send_message.assert_called_once_with(
- incoming.chat_id,
- "⏹ *Stopped\\.* Cancelled 1 request\\.",
- fire_and_forget=False,
- message_thread_id=None,
- )
+ handler.resolve_node_id.assert_awaited_once_with(incoming.scope, "status_root")
+ handler.stop_task.assert_awaited_once_with(incoming.scope, "root_msg")
+ handler.stop_all_tasks.assert_not_awaited()
+ mock_cli_manager.stop_all.assert_not_awaited()
+ assert "Cancelled 1 request" in mock_platform.queue_send_message.call_args.args[1]
@pytest.mark.asyncio
-async def test_handle_message_stop_command_reply_unknown_does_not_stop_all(
+async def test_reply_stop_unknown_does_not_stop_all(
handler, mock_platform, mock_cli_manager, incoming_message_factory
):
+ handler.resolve_node_id = AsyncMock(return_value=None)
+ handler.stop_all_tasks = AsyncMock(return_value=5)
incoming = incoming_message_factory(
text="/stop",
message_id="stop_msg",
reply_to_message_id="unknown_msg",
)
- handler.stop_all_tasks = AsyncMock(return_value=5)
-
await handler.handle_message(incoming)
- handler.stop_all_tasks.assert_not_called()
- mock_cli_manager.stop_all.assert_not_called()
- mock_platform.queue_send_message.assert_called_once_with(
- incoming.chat_id,
- "⏹ *Stopped\\.* Nothing to stop for that message\\.",
- fire_and_forget=False,
- message_thread_id=None,
+ handler.stop_all_tasks.assert_not_awaited()
+ mock_cli_manager.stop_all.assert_not_awaited()
+ assert (
+ "Nothing to stop for that message"
+ in mock_platform.queue_send_message.call_args.args[1]
)
@pytest.mark.asyncio
-async def test_handle_message_stats_command(
+async def test_stats_command_reports_cli_and_tree_counts(
handler, mock_platform, mock_cli_manager, incoming_message_factory
):
- incoming = incoming_message_factory(text="/stats")
mock_cli_manager.get_stats.return_value = {"active_sessions": 2}
- await handler.handle_message(incoming)
+ await handler.handle_message(incoming_message_factory(text="/stats"))
- mock_platform.queue_send_message.assert_called_once()
- args, kwargs = mock_platform.queue_send_message.call_args
- assert "Active CLI: 2" in args[1]
- assert kwargs["fire_and_forget"] is False
- assert kwargs.get("message_thread_id") is None
+ text = mock_platform.queue_send_message.call_args.args[1]
+ assert "Active CLI: 2" in text
+ assert "Message Trees: 0" in text
+ assert mock_platform.queue_send_message.call_args.kwargs["fire_and_forget"] is False
@pytest.mark.asyncio
-async def test_handle_message_filters_status_messages(
+async def test_status_echo_is_filtered(
handler, mock_platform, incoming_message_factory
):
- incoming = incoming_message_factory(text="⏳ Thinking...")
-
- await handler.handle_message(incoming)
+ await handler.handle_message(incoming_message_factory(text="⏳ Thinking..."))
- mock_platform.queue_send_message.assert_not_called()
+ mock_platform.queue_send_message.assert_not_awaited()
@pytest.mark.asyncio
-async def test_handle_message_new_conversation(
- handler, mock_platform, mock_session_store, incoming_message_factory
+async def test_new_turn_uses_public_admission_and_persists_exact_snapshot(
+ handler,
+ mock_platform,
+ mock_session_store,
+ incoming_message_factory,
):
- incoming = incoming_message_factory(text="hello")
+ incoming = incoming_message_factory(text="hello", message_id="node_1")
mock_platform.queue_send_message.return_value = "status_123"
- # We need to mock tree_queue methods
- with (
- patch.object(handler.tree_queue, "create_tree", AsyncMock()) as mock_create,
- patch.object(
- handler.tree_queue, "enqueue", AsyncMock(return_value=False)
- ) as mock_enqueue,
- ):
- mock_tree = MagicMock()
- mock_tree.root_id = "root_1"
- mock_tree.snapshot.return_value = {"data": "tree"}
- mock_create.return_value = mock_tree
-
- await handler.handle_message(incoming)
+ await handler.handle_message(incoming)
+ await _wait_for_idle(handler)
- mock_create.assert_called_once()
- mock_enqueue.assert_called_once()
- mock_session_store.save_tree_snapshot.assert_called_once_with({"data": "tree"})
+ assert "Launching" in mock_platform.queue_send_message.call_args.args[1]
+ assert mock_session_store.save_tree_snapshot.call_count >= 2
+ view = await handler.tree_queue.get_node(incoming.scope, "node_1")
+ assert view is not None
+ assert view.state is MessageState.COMPLETED
@pytest.mark.asyncio
-async def test_handle_message_queued(handler, mock_platform, incoming_message_factory):
- incoming = incoming_message_factory(text="hello", message_id="msg_1")
- mock_platform.queue_send_message.return_value = "status_123"
-
- with (
- patch.object(handler.tree_queue, "create_tree", AsyncMock()) as mock_create,
- patch.object(handler.tree_queue, "enqueue", AsyncMock(return_value=True)),
- patch.object(handler.tree_queue, "get_queue_size", MagicMock(return_value=3)),
- ):
- mock_tree = MagicMock()
- mock_tree.root_id = "root_1"
- mock_tree.snapshot.return_value = {}
- mock_create.return_value = mock_tree
+async def test_duplicate_delivery_removes_its_provisional_status(
+ handler,
+ mock_platform,
+ mock_session_store,
+ incoming_message_factory,
+):
+ incoming = incoming_message_factory(text="hello", message_id="duplicate")
+ mock_platform.queue_send_message.side_effect = ["status-first", "status-rejected"]
- await handler.handle_message(incoming)
+ await handler.handle_message(incoming)
+ await _wait_for_idle(handler)
+ await handler.handle_message(incoming)
- mock_platform.queue_edit_message.assert_called_once_with(
+ mock_platform.queue_delete_messages.assert_awaited_once_with(
+ incoming.chat_id,
+ ["status-rejected"],
+ fire_and_forget=False,
+ )
+ mock_session_store.forget_message_ids.assert_called_once_with(
+ incoming.platform,
incoming.chat_id,
- "status_123",
- "📋 *Queued* \\(position 3\\) \\- waiting\\.\\.\\.",
- parse_mode="MarkdownV2",
+ {"status-rejected"},
)
@pytest.mark.asyncio
-async def test_update_queue_positions(handler, mock_platform):
- root_incoming = IncomingMessage(
- text="Root",
- chat_id="chat_1",
- user_id="user_1",
- message_id="root",
- platform="telegram",
- )
- root = MessageNode(
- node_id="root",
- incoming=root_incoming,
- status_message_id="status_root",
- )
- tree = MessageTree(root)
-
- child_incoming_1 = IncomingMessage(
- text="Child 1",
- chat_id="chat_1",
- user_id="user_1",
- message_id="child_1",
- platform="telegram",
- reply_to_message_id="root",
- )
- child_incoming_2 = IncomingMessage(
- text="Child 2",
- chat_id="chat_1",
- user_id="user_1",
- message_id="child_2",
- platform="telegram",
- reply_to_message_id="root",
+async def test_pre_sent_status_is_edited_in_place(
+ handler, mock_platform, incoming_message_factory
+):
+ incoming = incoming_message_factory(
+ text="hello",
+ message_id="node_1",
+ status_message_id="existing_status",
)
- await tree.add_node(
- node_id="child_1",
- incoming=child_incoming_1,
- status_message_id="status_1",
- parent_id="root",
- )
- await tree.add_node(
- node_id="child_2",
- incoming=child_incoming_2,
- status_message_id="status_2",
- parent_id="root",
- )
+ await handler.handle_message(incoming)
+ await _wait_for_idle(handler)
- await tree.enqueue("child_1")
- await tree.enqueue("child_2")
+ first_edit = mock_platform.queue_edit_message.call_args_list[0]
+ assert first_edit.args[1] == "existing_status"
+ assert "Launching" in first_edit.args[2]
+ assert first_edit.kwargs["fire_and_forget"] is False
+ mock_platform.queue_send_message.assert_not_awaited()
- await handler.update_queue_positions(tree)
- calls = mock_platform.queue_edit_message.call_args_list
- assert len(calls) == 2
- assert calls[0][0][0] == "chat_1"
- assert calls[0][0][1] == "status_1"
- assert "position 1" in calls[0][0][2]
- assert calls[1][0][0] == "chat_1"
- assert calls[1][0][1] == "status_2"
- assert "position 2" in calls[1][0][2]
+async def test_busy_reply_is_rendered_with_atomic_queue_position(
+ handler, mock_platform, mock_cli_manager, incoming_message_factory
+):
+ started = asyncio.Event()
+ async def blocking_start(*args, **kwargs):
+ started.set()
+ await asyncio.sleep(60)
+ if False:
+ yield {}
-async def test_mark_node_processing(handler, mock_platform):
- root_incoming = IncomingMessage(
- text="Root",
- chat_id="chat_1",
- user_id="user_1",
- message_id="root",
- platform="telegram",
- )
- root = MessageNode(
- node_id="root",
- incoming=root_incoming,
- status_message_id="status_root",
+ session = MagicMock()
+ session.start_task = blocking_start
+ mock_cli_manager.get_or_create_session.return_value = (
+ session,
+ "session_1",
+ False,
)
- tree = MessageTree(root)
+ mock_platform.queue_send_message.side_effect = ["status_root", "status_child"]
- child_incoming = IncomingMessage(
- text="Child",
- chat_id="chat_1",
- user_id="user_1",
+ root = incoming_message_factory(text="root", message_id="root")
+ await handler.handle_message(root)
+ await started.wait()
+ child = incoming_message_factory(
+ text="child",
message_id="child",
- platform="telegram",
- reply_to_message_id="root",
+ reply_to_message_id="status_root",
)
+ await handler.handle_message(child)
- await tree.add_node(
- node_id="child",
- incoming=child_incoming,
- status_message_id="status_child",
- parent_id="root",
+ assert "position 1" in mock_platform.queue_send_message.call_args.args[1]
+ queued_edit = mock_platform.queue_edit_message.call_args_list[-1]
+ assert queued_edit.args[1] == "status_child"
+ assert "position 1" in queued_edit.args[2]
+
+ await handler.stop_all_tasks()
+
+
+async def test_queue_position_callback_consumes_immutable_entries(
+ handler, mock_platform
+):
+ queue = (
+ QueueEntry(
+ node=NodeUiTarget(
+ scope=_SCOPE,
+ node_id="child_1",
+ status_message_id="status_1",
+ ),
+ position=1,
+ ),
+ QueueEntry(
+ node=NodeUiTarget(
+ scope=_SCOPE,
+ node_id="child_2",
+ status_message_id="status_2",
+ ),
+ position=2,
+ ),
)
- await handler.mark_node_processing(tree, "child")
+ await handler.turn_intake.update_queue_positions(queue)
+ await asyncio.sleep(0)
- mock_platform.queue_edit_message.assert_called_once()
- args, kwargs = mock_platform.queue_edit_message.call_args
- assert args[0] == "chat_1"
- assert args[1] == "status_child"
- assert "Processing" in args[2]
- assert kwargs["parse_mode"] == "MarkdownV2"
+ calls = mock_platform.queue_edit_message.call_args_list
+ assert [call.args[1] for call in calls] == ["status_1", "status_2"]
+ assert "position 1" in calls[0].args[2]
+ assert "position 2" in calls[1].args[2]
@pytest.mark.asyncio
-async def test_stop_all_tasks(handler, mock_cli_manager, mock_platform):
- mock_node = MagicMock()
- mock_node.incoming.chat_id = "chat_1"
- mock_node.status_message_id = "status_1"
+async def test_claim_started_callback_renders_processing(handler, mock_platform):
+ claim = _claim()
- with patch.object(
- handler.tree_queue,
- "cancel_all",
- AsyncMock(
- return_value=[CancelledNode(mock_node, CancellationUiOwner.WORKFLOW)]
- ),
- ) as cancel_all:
- count = await handler.stop_all_tasks()
+ await handler.turn_intake.mark_node_processing(claim)
+ await asyncio.sleep(0)
- assert count == 1
- cancel_all.assert_awaited_once_with(reason=CancellationReason.STOP)
- mock_cli_manager.stop_all.assert_called_once()
- mock_platform.fire_and_forget.assert_called_once()
+ args, kwargs = mock_platform.queue_edit_message.call_args
+ assert args[0:2] == ("chat_1", "status_1")
+ assert "Processing" in args[2]
+ assert kwargs["parse_mode"] == "MarkdownV2"
@pytest.mark.asyncio
-async def test_stop_all_tasks_skips_direct_edit_for_active_runner_owned_node(
- handler, mock_cli_manager, mock_platform
+async def test_stop_all_applies_immutable_ui_ownership_and_snapshots(
+ handler, mock_cli_manager, mock_platform, mock_session_store
):
- """Active node cleanup owns transcript-preserving stopped rendering."""
- incoming = IncomingMessage(
- text="work",
- chat_id="chat_1",
- user_id="user_1",
- message_id="node_1",
- platform="telegram",
- )
- node = MessageNode(
- node_id="node_1", incoming=incoming, status_message_id="status_1"
- )
- tree = MagicMock()
- tree.root_id = "root_1"
- tree.snapshot.return_value = {"root": "snapshot"}
-
- with (
- patch.object(
- handler.tree_queue,
- "cancel_all",
- AsyncMock(return_value=[CancelledNode(node, CancellationUiOwner.RUNNER)]),
+ workflow_owned = CancellationEffect(
+ node=NodeUiTarget(
+ scope=_SCOPE,
+ node_id="queued",
+ status_message_id="status_queued",
),
- patch.object(
- handler.tree_queue, "get_tree_for_node", MagicMock(return_value=tree)
+ ui_owner=CancellationUiOwner.WORKFLOW,
+ )
+ runner_owned = CancellationEffect(
+ node=NodeUiTarget(
+ scope=_SCOPE,
+ node_id="active",
+ status_message_id="status_active",
),
- ):
+ ui_owner=CancellationUiOwner.RUNNER,
+ )
+ snapshot = _snapshot()
+ result = CancellationResult(
+ effects=(workflow_owned, runner_owned),
+ snapshots=(snapshot,),
+ )
+ with patch.object(
+ handler.tree_queue,
+ "cancel_all",
+ AsyncMock(return_value=result),
+ ) as cancel_all:
count = await handler.stop_all_tasks()
+ await asyncio.sleep(0)
- assert count == 1
- mock_cli_manager.stop_all.assert_called_once()
- mock_platform.fire_and_forget.assert_not_called()
- mock_platform.queue_edit_message.assert_not_called()
- handler.session_store.save_tree_snapshot.assert_called_once_with(
- {"root": "snapshot"}
- )
+ assert count == 2
+ cancel_all.assert_awaited_once_with(reason=CancellationReason.STOP)
+ mock_cli_manager.stop_all.assert_awaited_once()
+ assert mock_platform.fire_and_forget.call_count == 1
+ assert mock_platform.queue_edit_message.call_args.args[1] == "status_queued"
+ mock_session_store.save_tree_snapshot.assert_called_once_with(snapshot)
@pytest.mark.asyncio
-async def test_stop_all_tasks_edits_queued_workflow_owned_node(
- handler, mock_cli_manager, mock_platform
+async def test_stop_all_persists_committed_transition_before_cli_shutdown(
+ handler,
+ mock_cli_manager,
+ mock_session_store,
):
- """Queued nodes have no transcript owner, so workflow renders simple stop."""
- incoming = IncomingMessage(
- text="queued",
- chat_id="chat_1",
- user_id="user_1",
- message_id="node_1",
- platform="telegram",
- )
- node = MessageNode(
- node_id="node_1", incoming=incoming, status_message_id="status_1"
- )
+ shutdown_started = asyncio.Event()
+ snapshot = _snapshot()
+ result = CancellationResult(snapshots=(snapshot,))
+
+ async def block_shutdown() -> None:
+ shutdown_started.set()
+ await asyncio.Event().wait()
+ mock_cli_manager.stop_all.side_effect = block_shutdown
with patch.object(
handler.tree_queue,
"cancel_all",
- AsyncMock(return_value=[CancelledNode(node, CancellationUiOwner.WORKFLOW)]),
+ AsyncMock(return_value=result),
):
- count = await handler.stop_all_tasks()
-
- assert count == 1
- mock_platform.fire_and_forget.assert_called_once()
-
+ stop_task = asyncio.create_task(handler.stop_all_tasks())
+ await shutdown_started.wait()
-async def mock_async_gen(events):
- for e in events:
- yield e
+ mock_session_store.save_tree_snapshot.assert_called_once_with(snapshot)
+ stop_task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await stop_task
@pytest.mark.asyncio
-async def test_node_runner_process_node_success_flow(
- handler, mock_cli_manager, mock_platform
+async def test_node_runner_success_uses_claim_and_semantic_completion(
+ handler, mock_cli_manager, mock_platform, mock_session_store
):
- # Setup
- node_id = "node_1"
- mock_node = MagicMock()
- mock_node.incoming.chat_id = "chat_1"
- mock_node.incoming.text = "hello"
- mock_node.status_message_id = "status_1"
- mock_node.parent_id = None
-
- mock_session = MagicMock()
- # Mock start_task to return our async generator
- events = [
- {
- "type": "assistant",
- "message": {"content": [{"type": "thinking", "thinking": "Let me think"}]},
- },
- {
- "type": "assistant",
- "message": {"content": [{"type": "text", "text": "Hello world"}]},
- },
- {"type": "exit", "code": 0},
- ]
- mock_session.start_task.return_value = mock_async_gen(events)
-
+ claim = _claim(prompt="say hello")
+ session = _session(
+ [
+ {
+ "type": "assistant",
+ "message": {
+ "content": [
+ {"type": "thinking", "thinking": "Let me think"},
+ {"type": "text", "text": "Hello world"},
+ ]
+ },
+ },
+ {"type": "exit", "code": 0},
+ ]
+ )
mock_cli_manager.get_or_create_session.return_value = (
- mock_session,
+ session,
"session_1",
False,
)
-
- mock_tree = MagicMock()
- mock_tree.update_state = AsyncMock()
- mock_tree.root_id = "root_1"
- mock_tree.snapshot.return_value = {}
-
+ snapshot = _snapshot()
with patch.object(
- handler.tree_queue, "get_tree_for_node", MagicMock(return_value=mock_tree)
- ):
- 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)
- mock_tree.update_state.assert_any_call(
- node_id, MessageState.COMPLETED, session_id="session_1"
- )
-
- # Verify UI updates (at least the final one)
- # Note: update_ui is debounced, but COMPLETED/ERROR/CANCELLED are forced
- mock_platform.queue_edit_message.assert_called()
- last_call = mock_platform.queue_edit_message.call_args_list[-1]
- assert "✅ *Complete*" in last_call[0][2]
- assert "Hello world" in last_call[0][2]
+ handler.tree_queue,
+ "complete_claim",
+ AsyncMock(return_value=snapshot),
+ ) as complete_claim:
+ await handler.node_runner.process_node(claim)
+ complete_claim.assert_awaited_once_with(claim, "session_1")
+ mock_session_store.save_tree_snapshot.assert_called_once_with(snapshot)
+ rendered = mock_platform.queue_edit_message.call_args_list[-1].args[2]
+ assert "✅ *Complete*" in rendered
+ assert "Hello world" in rendered
mock_cli_manager.get_or_create_session.assert_awaited_once_with(session_id=None)
- mock_session.start_task.assert_called_once()
- st_kw = mock_session.start_task.call_args
- assert st_kw.kwargs.get("session_id") is None
- assert st_kw.kwargs.get("fork_session") is False
+ assert session.start_task.call_args.args == ("say hello",)
+ assert session.start_task.call_args.kwargs == {
+ "session_id": None,
+ "fork_session": False,
+ }
@pytest.mark.asyncio
-async def test_node_runner_process_node_reply_uses_parent_session_for_manager_and_fork(
- handler, mock_cli_manager, mock_platform
+async def test_node_runner_uses_claim_parent_session_for_fork(
+ handler, mock_cli_manager
):
- """Telegram follow-ups must reuse parent Claude session (issue #233)."""
- node_id = "child_1"
- mock_node = MagicMock()
- mock_node.incoming.chat_id = "chat_1"
- mock_node.incoming.text = "follow up"
- mock_node.status_message_id = "status_child"
- mock_node.parent_id = "root_msg"
-
- parent_claude_session = "claude_sess_parent"
- mock_session = MagicMock()
- mock_session.start_task.return_value = mock_async_gen([{"type": "exit", "code": 0}])
+ claim = _claim(parent_session_id="parent_session")
+ session = _session([{"type": "exit", "code": 0}])
mock_cli_manager.get_or_create_session.return_value = (
- mock_session,
- parent_claude_session,
+ session,
+ "child_session",
False,
)
- mock_tree = MagicMock()
- mock_tree.update_state = AsyncMock()
- mock_tree.root_id = "root_msg"
- mock_tree.snapshot.return_value = {}
- mock_tree.get_parent_session_id = MagicMock(return_value=parent_claude_session)
-
- with patch.object(
- handler.tree_queue, "get_tree_for_node", MagicMock(return_value=mock_tree)
- ):
- await handler.node_runner.process_node(node_id, mock_node)
+ await handler.node_runner.process_node(claim)
- mock_tree.get_parent_session_id.assert_called_once_with(node_id)
mock_cli_manager.get_or_create_session.assert_awaited_once_with(
- session_id=parent_claude_session
+ session_id="parent_session"
)
- mock_session.start_task.assert_called_once()
- st_kw = mock_session.start_task.call_args
- assert st_kw.kwargs.get("session_id") == parent_claude_session
- assert st_kw.kwargs.get("fork_session") is True
+ assert session.start_task.call_args.kwargs == {
+ "session_id": "parent_session",
+ "fork_session": True,
+ }
@pytest.mark.asyncio
-async def test_node_runner_process_node_error_flow(
- handler, mock_cli_manager, mock_platform
+async def test_session_info_records_real_session_through_manager(
+ handler, mock_cli_manager, mock_session_store
):
- node_id = "node_1"
- mock_node = MagicMock()
- mock_node.incoming.chat_id = "chat_1"
- mock_node.incoming.text = "hello"
- mock_node.status_message_id = "status_1"
-
- mock_session = MagicMock()
- events = [{"type": "error", "error": {"message": "CLI crashed"}}]
- mock_session.start_task.return_value = mock_async_gen(events)
+ claim = _claim()
+ session = _session(
+ [
+ {"type": "session_info", "session_id": "real_session"},
+ {"type": "exit", "code": 0},
+ ]
+ )
mock_cli_manager.get_or_create_session.return_value = (
- mock_session,
- "session_1",
- False,
+ session,
+ "temporary_session",
+ True,
)
-
- mock_tree = MagicMock()
- mock_tree.root_id = "root_1"
- mock_tree.snapshot.return_value = {"data": "tree"}
- mock_tree.update_state = AsyncMock()
-
+ record_snapshot = _snapshot("record")
+ complete_snapshot = _snapshot("complete")
with (
patch.object(
- handler.tree_queue, "get_tree_for_node", MagicMock(return_value=mock_tree)
- ),
+ handler.tree_queue,
+ "record_session",
+ AsyncMock(return_value=record_snapshot),
+ ) as record_session,
patch.object(
- handler.tree_queue, "mark_node_error", AsyncMock(return_value=[mock_node])
- ),
+ handler.tree_queue,
+ "complete_claim",
+ AsyncMock(return_value=complete_snapshot),
+ ) as complete_claim,
):
- 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_snapshot.assert_called_once_with(
- {"data": "tree"}
- )
+ await handler.node_runner.process_node(claim)
- last_call = mock_platform.queue_edit_message.call_args_list[-1]
- assert "❌ *Error*" in last_call[0][2]
- assert "CLI crashed" in last_call[0][2]
+ mock_cli_manager.register_real_session_id.assert_awaited_once_with(
+ "temporary_session", "real_session"
+ )
+ record_session.assert_awaited_once_with(claim, "real_session")
+ complete_claim.assert_awaited_once_with(claim, "real_session")
+ assert mock_session_store.save_tree_snapshot.call_args_list == [
+ ((record_snapshot,), {}),
+ ((complete_snapshot,), {}),
+ ]
@pytest.mark.asyncio
-async def test_node_runner_process_node_provider_error_exit_does_not_complete(
+async def test_session_limit_failure_uses_non_propagating_claim_failure(
handler, mock_cli_manager, mock_platform
):
- node_id = "node_1"
- mock_node = MagicMock()
- mock_node.incoming.chat_id = "chat_1"
- mock_node.incoming.text = "hello"
- mock_node.status_message_id = "status_1"
- mock_node.parent_id = None
-
- mock_session = MagicMock()
- events = [
- {
- "type": "error",
- "error": {
- "message": "API Error: Request rejected (429)\nProvider rate limit reached."
- },
- },
- {"type": "exit", "code": 1},
- ]
- mock_session.start_task.return_value = mock_async_gen(events)
+ claim = _claim()
+ mock_cli_manager.get_or_create_session.side_effect = RuntimeError("session limit")
+ result = FailureResult(
+ affected=(claim.node,),
+ queue_update=None,
+ snapshot=_snapshot(),
+ )
+ with patch.object(
+ handler.tree_queue,
+ "fail_claim",
+ AsyncMock(return_value=result),
+ ) as fail_claim:
+ await handler.node_runner.process_node(claim)
+
+ fail_claim.assert_awaited_once_with(claim, propagate=False)
+ rendered = mock_platform.queue_edit_message.call_args_list[-1].args[2]
+ assert "Session limit reached" in rendered
+
+
+async def test_non_exit_error_defers_child_failure_until_stream_ends(
+ handler, mock_cli_manager, mock_platform, mock_session_store
+):
+ claim = _claim()
+ session = _session([{"type": "error", "error": {"message": "CLI crashed"}}])
mock_cli_manager.get_or_create_session.return_value = (
- mock_session,
+ session,
"session_1",
False,
)
+ child = NodeUiTarget(
+ scope=_SCOPE,
+ node_id="child",
+ status_message_id="status_child",
+ )
+ snapshot = _snapshot()
+ result = FailureResult(
+ affected=(claim.node, child),
+ queue_update=None,
+ snapshot=snapshot,
+ )
+ with patch.object(
+ handler.tree_queue,
+ "fail_claim",
+ AsyncMock(return_value=result),
+ ) as fail_claim:
+ await handler.node_runner.process_node(claim)
+ await asyncio.sleep(0)
+
+ assert fail_claim.await_args_list == [
+ call(claim, propagate=False),
+ call(claim, propagate=True),
+ ]
+ assert mock_session_store.save_tree_snapshot.call_args_list == [
+ call(snapshot),
+ call(snapshot),
+ ]
+ rendered = "\n".join(
+ call.args[2] for call in mock_platform.queue_edit_message.call_args_list
+ )
+ assert "❌ *Error*" in rendered
+ assert "CLI crashed" in rendered
+ assert "Parent task failed" in rendered
- mock_tree = MagicMock()
- mock_tree.root_id = "root_1"
- mock_tree.snapshot.return_value = {"data": "tree"}
- mock_tree.update_state = AsyncMock()
+async def test_provider_error_exit_does_not_mask_or_complete(
+ handler, mock_cli_manager, mock_platform
+):
+ claim = _claim()
+ provider_error = "API Error: Request rejected (429)\nProvider rate limit reached."
+ session = _session(
+ [
+ {"type": "error", "error": {"message": provider_error}},
+ {"type": "exit", "code": 1},
+ ]
+ )
+ mock_cli_manager.get_or_create_session.return_value = (
+ session,
+ "session_1",
+ False,
+ )
+ failure = FailureResult(
+ affected=(claim.node,),
+ queue_update=None,
+ snapshot=_snapshot(),
+ )
with (
patch.object(
- handler.tree_queue, "get_tree_for_node", MagicMock(return_value=mock_tree)
- ),
+ handler.tree_queue,
+ "fail_claim",
+ AsyncMock(return_value=failure),
+ ) as fail_claim,
patch.object(
- handler.tree_queue, "mark_node_error", AsyncMock(return_value=[mock_node])
- ) as mark_node_error,
+ handler.tree_queue,
+ "complete_claim",
+ AsyncMock(),
+ ) as complete_claim,
):
- await handler.node_runner.process_node(node_id, mock_node)
-
- mark_node_error.assert_called_once_with(
- node_id,
- "API Error: Request rejected (429)\nProvider rate limit reached.",
- propagate_to_children=True,
- )
- mock_tree.update_state.assert_any_call(node_id, MessageState.IN_PROGRESS)
- assert not any(
- call.args == (node_id, MessageState.COMPLETED)
- or (
- len(call.args) >= 2
- and call.args[0] == node_id
- and call.args[1] is MessageState.COMPLETED
- )
- for call in mock_tree.update_state.call_args_list
- )
+ await handler.node_runner.process_node(claim)
+ assert fail_claim.await_args_list == [
+ call(claim, propagate=False),
+ call(claim, propagate=True),
+ ]
+ complete_claim.assert_not_awaited()
rendered = mock_platform.queue_edit_message.call_args_list[-1].args[2]
- assert "❌ *Error*" in rendered
assert "API Error: Request rejected" in rendered
assert "Process exited with code" not in rendered
assert "✅ *Complete*" not in rendered
@pytest.mark.asyncio
-async def test_node_runner_process_node_success_complete_wins_after_non_exit_error(
+async def test_success_exit_still_renders_complete_after_non_exit_error(
handler, mock_cli_manager, mock_platform
):
- node_id = "node_1"
- mock_node = MagicMock()
- mock_node.incoming.chat_id = "chat_1"
- mock_node.incoming.text = "hello"
- mock_node.status_message_id = "status_1"
- mock_node.parent_id = None
-
- mock_session = MagicMock()
- events = [
- {"type": "error", "error": {"message": "recoverable warning"}},
- {"type": "exit", "code": 0},
- ]
- mock_session.start_task.return_value = mock_async_gen(events)
+ claim = _claim()
+ session = _session(
+ [
+ {"type": "error", "error": {"message": "recoverable warning"}},
+ {"type": "exit", "code": 0},
+ ]
+ )
mock_cli_manager.get_or_create_session.return_value = (
- mock_session,
+ session,
"session_1",
False,
)
-
- mock_tree = MagicMock()
- mock_tree.root_id = "root_1"
- mock_tree.snapshot.return_value = {"data": "tree"}
- mock_tree.update_state = AsyncMock()
-
+ failure = FailureResult(
+ affected=(claim.node,),
+ queue_update=None,
+ snapshot=_snapshot(),
+ )
with (
patch.object(
- handler.tree_queue, "get_tree_for_node", MagicMock(return_value=mock_tree)
- ),
+ handler.tree_queue,
+ "fail_claim",
+ AsyncMock(return_value=failure),
+ ) as fail_claim,
patch.object(
- handler.tree_queue, "mark_node_error", AsyncMock(return_value=[mock_node])
- ) as mark_node_error,
+ handler.tree_queue,
+ "complete_claim",
+ AsyncMock(return_value=_snapshot()),
+ ) as complete_claim,
):
- await handler.node_runner.process_node(node_id, mock_node)
+ await handler.node_runner.process_node(claim)
+
+ fail_claim.assert_awaited_once_with(
+ claim,
+ propagate=False,
+ )
+ complete_claim.assert_awaited_once_with(claim, "session_1")
+ assert (
+ "✅ *Complete*" in mock_platform.queue_edit_message.call_args_list[-1].args[2]
+ )
+
- mark_node_error.assert_called_once_with(
- node_id,
- "recoverable warning",
- propagate_to_children=True,
+async def test_unexpected_runner_exception_uses_detailed_task_failed_ui(
+ handler, mock_cli_manager, mock_platform
+):
+ claim = _claim()
+
+ async def failing_start(*args, **kwargs):
+ raise ValueError("runner exploded")
+ if False:
+ yield {}
+
+ session = MagicMock()
+ session.start_task = failing_start
+ mock_cli_manager.get_or_create_session.return_value = (
+ session,
+ "session_1",
+ False,
+ )
+ failure = FailureResult(
+ affected=(claim.node,),
+ queue_update=None,
+ snapshot=_snapshot(),
)
- mock_tree.update_state.assert_any_call(
- node_id, MessageState.COMPLETED, session_id="session_1"
+ with patch.object(
+ handler.tree_queue,
+ "fail_claim",
+ AsyncMock(return_value=failure),
+ ) as fail_claim:
+ await handler.node_runner.process_node(claim)
+
+ fail_claim.assert_awaited_once_with(
+ claim,
+ propagate=True,
)
rendered = mock_platform.queue_edit_message.call_args_list[-1].args[2]
- assert "✅ *Complete*" in rendered
+ assert "Task Failed" in rendered
+ assert "runner exploded" in rendered
@pytest.mark.asyncio
-async def test_node_runner_stop_cancellation_preserves_transcript(
+async def test_stop_cancellation_preserves_partial_transcript(
handler, mock_cli_manager, mock_platform
):
+ claim = _claim(prompt="work")
started = asyncio.Event()
async def start_task(*args, **kwargs):
@@ -730,345 +750,433 @@ async def test_node_runner_stop_cancellation_preserves_transcript(
"message": {"content": [{"type": "text", "text": "partial answer"}]},
}
started.set()
- try:
- await asyncio.sleep(60)
- except asyncio.CancelledError:
- raise
+ await asyncio.sleep(60)
- mock_session = MagicMock()
- mock_session.start_task = start_task
+ session = MagicMock()
+ session.start_task = start_task
mock_cli_manager.get_or_create_session.return_value = (
- mock_session,
+ session,
"session_1",
False,
)
-
- incoming = IncomingMessage(
- text="work",
- chat_id="chat_1",
- user_id="user_1",
- message_id="node_1",
- platform="telegram",
+ failure = FailureResult(
+ affected=(claim.node,),
+ queue_update=None,
+ snapshot=_snapshot(),
)
- node = MessageNode(
- node_id="node_1", incoming=incoming, status_message_id="status_1"
+ with patch.object(
+ handler.tree_queue,
+ "fail_claim",
+ AsyncMock(return_value=failure),
+ ) as fail_claim:
+ task = asyncio.create_task(handler.node_runner.process_node(claim))
+ await started.wait()
+ task.cancel(CancellationReason.STOP)
+ await task
+
+ fail_claim.assert_awaited_once_with(
+ claim,
+ propagate=False,
)
- node.set_context({"cancel_reason": "stop"})
-
- tree = await handler.tree_queue.create_tree("node_1", incoming, "status_1")
- task = asyncio.create_task(handler.node_runner.process_node("node_1", node))
- await started.wait()
-
- task.cancel()
- await task
-
- last_call = mock_platform.queue_edit_message.call_args_list[-1]
- rendered = last_call.args[2]
+ rendered = mock_platform.queue_edit_message.call_args_list[-1].args[2]
assert "partial answer" in rendered
assert "⏹ *Stopped\\.*" in rendered
assert rendered.index("partial answer") < rendered.index("⏹ *Stopped\\.*")
- assert tree.get_node("node_1").state == MessageState.ERROR
@pytest.mark.asyncio
-async def test_handle_message_clear_command_stops_deletes_and_wipes_state(
- handler, mock_platform, mock_session_store, incoming_message_factory
+async def test_global_clear_command_deletes_returned_ids(
+ handler, mock_platform, incoming_message_factory
):
- # Create some tracked messages across two chats. /clear should only delete
- # messages for the current chat.
- root_1 = incoming_message_factory(
- text="do something",
+ handler.clear_all_state = AsyncMock(return_value=frozenset({"100", "101"}))
+ incoming = incoming_message_factory(
+ text="/clear",
chat_id="chat_1",
- message_id="100",
- reply_to_message_id=None,
+ message_id="150",
)
- await handler.tree_queue.create_tree(
- node_id="100",
- incoming=root_1,
- status_message_id="101",
+
+ await handler.handle_message(incoming)
+
+ handler.clear_all_state.assert_awaited_once_with("telegram", "chat_1")
+ mock_platform.queue_delete_messages.assert_awaited_once_with(
+ "chat_1",
+ ["150", "101", "100"],
+ fire_and_forget=False,
)
+ mock_platform.queue_send_message.assert_not_awaited()
+
+async def test_clear_all_state_is_chat_scoped_for_deletes_and_global_for_fcc_state(
+ handler, mock_cli_manager, mock_session_store, incoming_message_factory
+):
+ root_1 = incoming_message_factory(
+ text="one",
+ chat_id="chat_1",
+ message_id="100",
+ )
root_2 = incoming_message_factory(
- text="other chat",
+ text="two",
chat_id="chat_2",
message_id="200",
- reply_to_message_id=None,
- )
- await handler.tree_queue.create_tree(
- node_id="200",
- incoming=root_2,
- status_message_id="201",
- )
-
- events = []
-
- async def _stop():
- events.append("stop")
- return 0
-
- async def _del_many(chat_id, message_ids, fire_and_forget=True):
- events.append(("del", chat_id, tuple(message_ids), fire_and_forget))
-
- handler.stop_all_tasks = AsyncMock(side_effect=_stop)
- mock_platform.queue_delete_messages = AsyncMock(side_effect=_del_many)
-
- incoming = incoming_message_factory(
- text="/clear", chat_id="chat_1", message_id="150"
)
- await handler.handle_message(incoming)
+ await handler.tree_queue.admit(root_1, "101")
+ await handler.tree_queue.admit(root_2, "201")
+ await _wait_for_idle(handler)
+ mock_session_store.get_message_ids_for_chat.return_value = ["42"]
+ mock_session_store.reset_mock()
+ mock_session_store.get_message_ids_for_chat.return_value = ["42"]
- assert events and events[0] == "stop"
- deleted_ids = set(events[1][2])
- assert deleted_ids == {"100", "101", "150"}
- assert events[1][3] is False
+ message_ids = await handler.clear_all_state("telegram", "chat_1")
+ assert message_ids == frozenset({"42", "100", "101"})
+ assert "200" not in message_ids
+ assert handler.get_tree_count() == 0
+ mock_cli_manager.stop_all.assert_awaited_once()
mock_session_store.clear_all.assert_called_once()
- assert handler.tree_queue.get_tree_count() == 0
- mock_platform.queue_send_message.assert_not_called()
@pytest.mark.asyncio
-async def test_handle_message_clear_command_with_mention(
- handler, mock_platform, mock_session_store, incoming_message_factory
+async def test_cancelled_global_clear_before_commit_preserves_tree_and_store(
+ handler,
+ mock_cli_manager,
+ mock_session_store,
+ incoming_message_factory,
):
- handler.stop_all_tasks = AsyncMock(return_value=0)
-
- incoming = incoming_message_factory(
- text="/clear@MyBot", chat_id="chat_1", message_id="10"
- )
- await handler.handle_message(incoming)
+ root = incoming_message_factory(text="work", message_id="100")
+ await handler.tree_queue.admit(root, "101")
+ await _wait_for_idle(handler)
+ initial_epoch = handler._admission_epoch
+ id_read_started = asyncio.Event()
+
+ async def block_id_read(platform: str, chat_id: str) -> set[str]:
+ id_read_started.set()
+ await asyncio.Future()
+ raise AssertionError("unreachable")
+
+ mock_session_store.reset_mock()
+ with patch.object(
+ handler.tree_queue,
+ "get_message_ids_for_chat",
+ new=block_id_read,
+ ):
+ clear_task = asyncio.create_task(
+ handler.clear_all_state("telegram", root.chat_id)
+ )
+ await id_read_started.wait()
+ clear_task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await clear_task
- handler.stop_all_tasks.assert_called_once()
- mock_platform.queue_delete_messages.assert_called_once_with(
- "chat_1",
- ["10"],
- fire_and_forget=False,
- )
- mock_session_store.clear_all.assert_called_once()
+ assert handler._admission_epoch == initial_epoch
+ assert handler.get_tree_count() == 1
+ mock_session_store.clear_all.assert_not_called()
+ mock_session_store.clear_conversation_snapshot.assert_not_called()
+ mock_cli_manager.stop_all.assert_not_awaited()
@pytest.mark.asyncio
-async def test_handle_message_clear_command_deletes_message_log_ids(
- handler, mock_platform, mock_session_store, incoming_message_factory
+async def test_clear_with_mention_uses_same_global_command(
+ handler, mock_platform, incoming_message_factory
):
- handler.stop_all_tasks = AsyncMock(return_value=0)
- mock_session_store.get_message_ids_for_chat.return_value = ["42", "43"]
-
+ handler.clear_all_state = AsyncMock(return_value=frozenset())
incoming = incoming_message_factory(
- text="/clear", chat_id="chat_1", message_id="150"
+ text="/clear@MyBot",
+ chat_id="chat_1",
+ message_id="10",
)
+
await handler.handle_message(incoming)
- mock_platform.queue_delete_messages.assert_called_once_with(
+ handler.clear_all_state.assert_awaited_once_with("telegram", "chat_1")
+ mock_platform.queue_delete_messages.assert_awaited_once_with(
"chat_1",
- ["150", "43", "42"],
+ ["10"],
fire_and_forget=False,
)
@pytest.mark.asyncio
-async def test_handle_message_clear_command_continues_after_delete_failure(
- handler, mock_platform, mock_session_store, incoming_message_factory
+async def test_clear_continues_after_platform_delete_failure(
+ handler, mock_platform, incoming_message_factory
):
- handler.stop_all_tasks = AsyncMock(return_value=0)
- mock_session_store.get_message_ids_for_chat.return_value = ["41", "42", "43"]
-
- async def delete_messages(chat_id, message_ids, fire_and_forget=True):
- raise RuntimeError("platform rejected delete")
-
- mock_platform.queue_delete_messages = AsyncMock(side_effect=delete_messages)
-
- incoming = incoming_message_factory(
- text="/clear", chat_id="chat_1", message_id="150"
+ handler.clear_all_state = AsyncMock(return_value=frozenset({"41", "42"}))
+ mock_platform.queue_delete_messages.side_effect = RuntimeError(
+ "platform rejected delete"
)
- await handler.handle_message(incoming)
- mock_platform.queue_delete_messages.assert_called_once_with(
- "chat_1",
- ["150", "43", "42", "41"],
- fire_and_forget=False,
+ await handler.handle_message(
+ incoming_message_factory(text="/clear", message_id="150")
)
- mock_session_store.clear_all.assert_called_once()
+
+ handler.clear_all_state.assert_awaited_once()
+ mock_platform.queue_delete_messages.assert_awaited_once()
@pytest.mark.asyncio
-async def test_handle_message_clear_command_reply_clears_branch(
- handler, mock_platform, mock_session_store, incoming_message_factory
+async def test_reply_clear_removes_only_branch_and_persists_remaining_tree(
+ handler,
+ mock_platform,
+ mock_session_store,
+ incoming_message_factory,
):
- """Reply /clear to a message clears only that branch."""
- root_incoming = incoming_message_factory(
- text="root", chat_id="chat_1", message_id="100", reply_to_message_id=None
- )
- tree = await handler.tree_queue.create_tree(
- node_id="100", incoming=root_incoming, status_message_id="101"
- )
- handler.tree_queue.register_node("101", tree.root_id)
-
- child_incoming = incoming_message_factory(
+ root = incoming_message_factory(text="root", message_id="100")
+ child = incoming_message_factory(
text="child",
- chat_id="chat_1",
message_id="102",
reply_to_message_id="100",
)
- await handler.tree_queue.add_to_tree(
- parent_node_id="100",
- node_id="102",
- incoming=child_incoming,
- status_message_id="103",
- )
-
- deleted_ids = []
+ await handler.tree_queue.admit(root, "101")
+ await _wait_for_idle(handler)
+ await handler.tree_queue.admit(child, "103", parent_node_id="100")
+ await _wait_for_idle(handler)
+ mock_session_store.reset_mock()
+ deleted_ids: list[str] = []
- async def _capture_delete(chat_id, message_ids, fire_and_forget=True):
+ async def capture_delete(chat_id, message_ids, fire_and_forget=True):
deleted_ids.extend(message_ids)
- mock_platform.queue_delete_messages = AsyncMock(side_effect=_capture_delete)
-
- incoming = incoming_message_factory(
- text="/clear",
- chat_id="chat_1",
- message_id="150",
- reply_to_message_id="102",
+ mock_platform.queue_delete_messages.side_effect = capture_delete
+ await handler.handle_message(
+ incoming_message_factory(
+ text="/clear",
+ message_id="150",
+ reply_to_message_id="103",
+ )
)
- await handler.handle_message(incoming)
assert set(deleted_ids) == {"102", "103", "150"}
assert "100" not in deleted_ids
assert "101" not in deleted_ids
- mock_session_store.save_tree_snapshot.assert_called()
+ assert await handler.tree_queue.get_node(root.scope, "102") is None
+ assert await handler.tree_queue.get_node(root.scope, "100") is not None
+ mock_session_store.save_tree_snapshot.assert_called_once()
mock_session_store.forget_message_ids.assert_called_once_with(
- "telegram", "chat_1", {"102", "103", "150"}
+ "telegram",
+ "chat_1",
+ {"102", "103", "150"},
)
- assert handler.tree_queue.get_tree_for_node("102") is None
- assert handler.tree_queue.get_tree_for_node("100") is not None
@pytest.mark.asyncio
-async def test_handle_message_clear_command_reply_unknown_sends_nothing(
+async def test_reply_clear_unknown_reports_nothing_to_clear(
handler, mock_platform, mock_session_store, incoming_message_factory
):
- """Reply /clear to unknown message sends 'Nothing to clear'."""
incoming = incoming_message_factory(
text="/clear",
- chat_id="chat_1",
message_id="150",
reply_to_message_id="999",
)
+
await handler.handle_message(incoming)
- mock_platform.queue_send_message.assert_called_once()
- call_args = mock_platform.queue_send_message.call_args[0]
- assert "Nothing to clear" in call_args[1]
+ assert "Nothing to clear" in mock_platform.queue_send_message.call_args.args[1]
mock_session_store.clear_all.assert_not_called()
@pytest.mark.asyncio
-async def test_handle_message_clear_command_reply_to_root_clears_tree(
- handler, mock_platform, mock_session_store, incoming_message_factory
+async def test_reply_clear_root_removes_tree_snapshot(
+ handler,
+ mock_platform,
+ mock_session_store,
+ incoming_message_factory,
):
- """Reply /clear to root message clears entire tree."""
- root_incoming = incoming_message_factory(
- text="root", chat_id="chat_1", message_id="100", reply_to_message_id=None
- )
- await handler.tree_queue.create_tree(
- node_id="100", incoming=root_incoming, status_message_id="101"
- )
-
- deleted_ids = []
+ root = incoming_message_factory(text="root", message_id="100")
+ await handler.tree_queue.admit(root, "101")
+ await _wait_for_idle(handler)
+ mock_session_store.reset_mock()
+ deleted_ids: list[str] = []
- async def _capture_delete(chat_id, message_ids, fire_and_forget=True):
+ async def capture_delete(chat_id, message_ids, fire_and_forget=True):
deleted_ids.extend(message_ids)
- mock_platform.queue_delete_messages = AsyncMock(side_effect=_capture_delete)
-
- incoming = incoming_message_factory(
- text="/clear",
- chat_id="chat_1",
- message_id="150",
- reply_to_message_id="100",
+ mock_platform.queue_delete_messages.side_effect = capture_delete
+ await handler.handle_message(
+ incoming_message_factory(
+ text="/clear",
+ message_id="150",
+ reply_to_message_id="100",
+ )
)
- await handler.handle_message(incoming)
assert set(deleted_ids) == {"100", "101", "150"}
- mock_session_store.remove_tree_snapshot.assert_called_once_with("100")
- mock_session_store.forget_message_ids.assert_called_once_with(
- "telegram", "chat_1", {"100", "101", "150"}
+ mock_session_store.remove_tree_snapshot.assert_called_once_with(
+ TreeIdentity(scope=root.scope, root_id="100")
)
- assert handler.tree_queue.get_tree_count() == 0
+ assert handler.get_tree_count() == 0
@pytest.mark.asyncio
-async def test_cancelled_node_runner_does_not_save_after_clear_replaces_queue(
+async def test_late_cancelled_runner_cannot_save_after_global_clear(
handler, mock_cli_manager, mock_session_store, incoming_message_factory
):
- """Late cancellation cleanup must not restore a tree after /clear reset."""
started = asyncio.Event()
- async def start_task(*args, **kwargs):
+ async def blocking_start(*args, **kwargs):
started.set()
- try:
- await asyncio.sleep(60)
- except asyncio.CancelledError:
- raise
+ await asyncio.sleep(60)
if False:
yield {}
- cli_session = MagicMock()
- cli_session.start_task = start_task
+ session = MagicMock()
+ session.start_task = blocking_start
mock_cli_manager.get_or_create_session.return_value = (
- cli_session,
+ session,
"pending_1",
True,
)
-
- incoming = incoming_message_factory(text="work", chat_id="chat_1", message_id="100")
- tree = await handler.tree_queue.create_tree("100", incoming, "101")
- node = tree.get_node("100")
- assert node is not None
-
- task = asyncio.create_task(handler.node_runner.process_node("100", node))
- await started.wait()
- handler.replace_tree_queue(
- TreeQueueManager(
- queue_update_callback=handler.update_queue_positions,
- node_started_callback=handler.mark_node_processing,
- )
+ await handler.handle_message(
+ incoming_message_factory(text="work", message_id="100")
)
+ await started.wait()
+ mock_session_store.reset_mock()
- task.cancel()
- await task
+ await handler.clear_all_state("telegram", "chat_1")
mock_session_store.save_tree_snapshot.assert_not_called()
+ mock_session_store.clear_all.assert_called_once()
+ assert handler.get_tree_count() == 0
@pytest.mark.asyncio
-async def test_handle_message_clear_command_reply_pending_voice_cancels(
- handler, mock_platform, mock_session_store, incoming_message_factory
+async def test_global_clear_removes_snapshot_saved_during_detach_window(
+ tmp_path,
+ mock_platform,
+ mock_cli_manager,
+ incoming_message_factory,
+):
+ runner_started = asyncio.Event()
+ release_runner = asyncio.Event()
+ id_read_started = asyncio.Event()
+ release_id_read = asyncio.Event()
+
+ async def finish_after_release(*args, **kwargs):
+ runner_started.set()
+ await release_runner.wait()
+ yield {"type": "exit", "code": 0}
+
+ session = MagicMock()
+ session.start_task = finish_after_release
+ mock_cli_manager.get_or_create_session.return_value = (
+ session,
+ "session_1",
+ False,
+ )
+ mock_platform.queue_send_message.return_value = "status-new"
+ store_path = tmp_path / "sessions.json"
+ store = SessionStore(storage_path=str(store_path))
+ workflow = MessagingWorkflow(
+ mock_platform,
+ mock_cli_manager,
+ store,
+ platform_name="telegram",
+ )
+ incoming = incoming_message_factory(text="work", message_id="new")
+ await workflow.handle_message(incoming)
+ await runner_started.wait()
+
+ get_ids = workflow.tree_queue.get_message_ids_for_chat
+
+ async def block_id_read(platform: str, chat_id: str) -> set[str]:
+ id_read_started.set()
+ await release_id_read.wait()
+ return await get_ids(platform, chat_id)
+
+ try:
+ with patch.object(
+ workflow.tree_queue,
+ "get_message_ids_for_chat",
+ new=block_id_read,
+ ):
+ clear_task = asyncio.create_task(
+ workflow.clear_all_state("telegram", incoming.chat_id)
+ )
+ await id_read_started.wait()
+ release_runner.set()
+ await _wait_for_idle(workflow)
+
+ assert not store.load_conversation_snapshot().is_empty
+ store.flush_pending_save()
+ assert (
+ not SessionStore(storage_path=str(store_path))
+ .load_conversation_snapshot()
+ .is_empty
+ )
+ release_id_read.set()
+ await clear_task
+
+ assert store.load_conversation_snapshot().is_empty
+ assert (
+ SessionStore(storage_path=str(store_path))
+ .load_conversation_snapshot()
+ .is_empty
+ )
+ finally:
+ release_runner.set()
+ release_id_read.set()
+ workflow.close()
+
+
+async def test_global_clear_invalidates_inflight_prompt_without_waiting_for_status(
+ handler,
+ mock_platform,
+ incoming_message_factory,
):
- """Reply /clear to a voice note during transcription cancels it."""
+ status_send_started = asyncio.Event()
+ release_status_send = asyncio.Event()
+
+ async def block_status_send(*args, **kwargs):
+ status_send_started.set()
+ await release_status_send.wait()
+ return "status-new"
+
+ mock_platform.queue_send_message.side_effect = block_status_send
+ prompt_task = asyncio.create_task(
+ handler.handle_message(
+ incoming_message_factory(text="new prompt", message_id="new")
+ )
+ )
+ await status_send_started.wait()
+ clear_task = asyncio.create_task(handler.clear_all_state("telegram", "chat_1"))
+
+ try:
+ await asyncio.wait_for(clear_task, timeout=1)
+ release_status_send.set()
+ await prompt_task
+ assert handler.get_tree_count() == 0
+ mock_platform.queue_delete_messages.assert_awaited_once_with(
+ "chat_1",
+ ["status-new"],
+ fire_and_forget=False,
+ )
+ finally:
+ release_status_send.set()
+ if not prompt_task.done():
+ prompt_task.cancel()
+ if not clear_task.done():
+ clear_task.cancel()
- async def cancel_pending(chat_id, reply_id):
- if reply_id == "100":
- return ("100", "101")
- return None
- mock_platform.cancel_pending_voice = AsyncMock(side_effect=cancel_pending)
- deleted_ids = []
+async def test_reply_clear_pending_voice_cancels_and_reports(
+ handler, mock_platform, incoming_message_factory
+):
+ mock_platform.cancel_pending_voice.return_value = ("100", "101")
+ deleted_ids: list[str] = []
- async def _capture_delete(chat_id, message_ids, fire_and_forget=True):
+ async def capture_delete(chat_id, message_ids, fire_and_forget=True):
deleted_ids.extend(message_ids)
- mock_platform.queue_delete_messages = AsyncMock(side_effect=_capture_delete)
-
+ mock_platform.queue_delete_messages.side_effect = capture_delete
incoming = incoming_message_factory(
text="/clear",
- chat_id="chat_1",
message_id="150",
reply_to_message_id="100",
)
+
await handler.handle_message(incoming)
- mock_platform.cancel_pending_voice.assert_called_once_with("chat_1", "100")
+ mock_platform.cancel_pending_voice.assert_awaited_once_with(incoming.scope, "100")
assert set(deleted_ids) == {"100", "101", "150"}
- call_args = mock_platform.queue_send_message.call_args[0]
- assert "Voice note cancelled" in call_args[1]
+ assert "Voice note cancelled" in mock_platform.queue_send_message.call_args.args[1]
diff --git a/tests/messaging/test_handler_context_isolation.py b/tests/messaging/test_handler_context_isolation.py
index fe6e2678..6470e915 100644
--- a/tests/messaging/test_handler_context_isolation.py
+++ b/tests/messaging/test_handler_context_isolation.py
@@ -1,158 +1,93 @@
+import asyncio
from unittest.mock import AsyncMock, MagicMock
import pytest
-from free_claude_code.messaging.trees import MessageState
from free_claude_code.messaging.workflow import MessagingWorkflow
-async def _gen_session(events):
- for e in events:
- yield e
+async def _wait_for_idle(handler: MessagingWorkflow) -> None:
+ for _ in range(100):
+ if handler.tree_queue.task_count() == 0:
+ return
+ await asyncio.sleep(0)
+ raise AssertionError("messaging claims did not finish")
-def handler(mock_platform, mock_cli_manager, mock_session_store):
- return MessagingWorkflow(mock_platform, mock_cli_manager, mock_session_store)
+def _session_factory(calls: list[tuple[str, str | None, bool]]):
+ async def get_or_create_session(session_id=None):
+ session = MagicMock()
-
-async def test_sibling_replies_fork_from_parent_session_id(
- handler, mock_cli_manager, incoming_message_factory
-):
- # Root node A with a known session_id.
- root_incoming = incoming_message_factory(text="A", message_id="A")
- tree = await handler.tree_queue.create_tree(
- node_id="A", incoming=root_incoming, status_message_id="status_A"
- )
- await tree.update_state("A", MessageState.COMPLETED, session_id="sess_A")
-
- # Add two sibling replies R1 and R2 under A.
- r1_incoming = incoming_message_factory(
- text="R1", message_id="R1", reply_to_message_id="A"
- )
- r2_incoming = incoming_message_factory(
- text="R2", message_id="R2", reply_to_message_id="A"
- )
- _, r1_node = await handler.tree_queue.add_to_tree(
- "A", "R1", r1_incoming, "status_R1"
- )
- _, r2_node = await handler.tree_queue.add_to_tree(
- "A", "R2", r2_incoming, "status_R2"
- )
-
- # Mock a fresh cli_session per node.
- calls = []
-
- async def _get_or_create_session(session_id=None):
- cli_session = MagicMock()
-
- async def _start_task(prompt, session_id=None, fork_session=False):
+ async def start_task(prompt, session_id=None, fork_session=False):
calls.append((prompt, session_id, fork_session))
- child_sid = f"sess_{prompt}"
- async for ev in _gen_session(
- [
- {"type": "session_info", "session_id": child_sid},
- {"type": "exit", "code": 0, "stderr": None},
- ]
- ):
- yield ev
-
- cli_session.start_task = _start_task
- return cli_session, f"pending_{len(calls) + 1}", True
-
- mock_cli_manager.get_or_create_session = AsyncMock(
- side_effect=_get_or_create_session
- )
+ yield {"type": "session_info", "session_id": f"sess_{prompt}"}
+ yield {"type": "exit", "code": 0, "stderr": None}
- await handler.node_runner.process_node("R1", r1_node)
- await handler.node_runner.process_node("R2", r2_node)
+ session.start_task = start_task
+ return session, f"pending_{len(calls)}", True
- # Both siblings must resume from the same parent session and fork.
- assert calls[0][0] == "R1"
- assert calls[0][1] == "sess_A"
- assert calls[0][2] is True
-
- assert calls[1][0] == "R2"
- assert calls[1][1] == "sess_A"
- assert calls[1][2] is True
+ return get_or_create_session
@pytest.mark.asyncio
-async def test_grandchild_reply_forks_from_branch_session(
- handler, mock_cli_manager, incoming_message_factory
-):
- root_incoming = incoming_message_factory(text="A", message_id="A")
- tree = await handler.tree_queue.create_tree(
- node_id="A", incoming=root_incoming, status_message_id="status_A"
+async def test_sibling_replies_fork_from_parent_session_id(
+ mock_platform,
+ mock_cli_manager,
+ mock_session_store,
+ incoming_message_factory,
+) -> None:
+ calls: list[tuple[str, str | None, bool]] = []
+ mock_cli_manager.get_or_create_session = AsyncMock(
+ side_effect=_session_factory(calls)
+ )
+ mock_platform.queue_send_message = AsyncMock(
+ side_effect=["status_A", "status_R1", "status_R2"]
)
- await tree.update_state("A", MessageState.COMPLETED, session_id="sess_A")
+ handler = MessagingWorkflow(mock_platform, mock_cli_manager, mock_session_store)
- r1_incoming = incoming_message_factory(
- text="R1", message_id="R1", reply_to_message_id="A"
+ await handler.handle_message(incoming_message_factory(text="A", message_id="A"))
+ await _wait_for_idle(handler)
+ await handler.handle_message(
+ incoming_message_factory(text="R1", message_id="R1", reply_to_message_id="A")
)
- _, r1_node = await handler.tree_queue.add_to_tree(
- "A", "R1", r1_incoming, "status_R1"
+ await _wait_for_idle(handler)
+ await handler.handle_message(
+ incoming_message_factory(text="R2", message_id="R2", reply_to_message_id="A")
)
+ await _wait_for_idle(handler)
- calls = []
+ assert calls == [
+ ("A", None, False),
+ ("R1", "sess_A", True),
+ ("R2", "sess_A", True),
+ ]
- async def _get_or_create_session(session_id=None):
- cli_session = MagicMock()
-
- async def _start_task(prompt, session_id=None, fork_session=False):
- calls.append((prompt, session_id, fork_session))
- # R1 gets its own forked session id.
- child_sid = "sess_R1"
- async for ev in _gen_session(
- [
- {"type": "session_info", "session_id": child_sid},
- {"type": "exit", "code": 0, "stderr": None},
- ]
- ):
- yield ev
-
- cli_session.start_task = _start_task
- return cli_session, "pending_R1", True
+async def test_grandchild_reply_forks_from_branch_session(
+ mock_platform,
+ mock_cli_manager,
+ mock_session_store,
+ incoming_message_factory,
+) -> None:
+ calls: list[tuple[str, str | None, bool]] = []
mock_cli_manager.get_or_create_session = AsyncMock(
- side_effect=_get_or_create_session
+ side_effect=_session_factory(calls)
)
-
- 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.
- c1_incoming = incoming_message_factory(
- text="C1", message_id="C1", reply_to_message_id="R1"
+ mock_platform.queue_send_message = AsyncMock(
+ side_effect=["status_A", "status_R1", "status_C1"]
)
- _, c1_node = await handler.tree_queue.add_to_tree(
- "R1", "C1", c1_incoming, "status_C1"
- )
-
- async def _get_or_create_session_c1(session_id=None):
- cli_session = MagicMock()
-
- async def _start_task(prompt, session_id=None, fork_session=False):
- calls.append((prompt, session_id, fork_session))
- async for ev in _gen_session(
- [
- {"type": "session_info", "session_id": "sess_C1"},
- {"type": "exit", "code": 0, "stderr": None},
- ]
- ):
- yield ev
+ handler = MessagingWorkflow(mock_platform, mock_cli_manager, mock_session_store)
- cli_session.start_task = _start_task
- return cli_session, "pending_C1", True
-
- mock_cli_manager.get_or_create_session = AsyncMock(
- side_effect=_get_or_create_session_c1
+ await handler.handle_message(incoming_message_factory(text="A", message_id="A"))
+ await _wait_for_idle(handler)
+ await handler.handle_message(
+ incoming_message_factory(text="R1", message_id="R1", reply_to_message_id="A")
)
+ await _wait_for_idle(handler)
+ await handler.handle_message(
+ incoming_message_factory(text="C1", message_id="C1", reply_to_message_id="R1")
+ )
+ await _wait_for_idle(handler)
- 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"
- assert calls[-1][1] == "sess_R1"
- assert calls[-1][2] is True
+ assert calls[-1] == ("C1", "sess_R1", True)
diff --git a/tests/messaging/test_handler_integration.py b/tests/messaging/test_handler_integration.py
index 24e0ece7..bb85a188 100644
--- a/tests/messaging/test_handler_integration.py
+++ b/tests/messaging/test_handler_integration.py
@@ -1,35 +1,43 @@
import asyncio
-from unittest.mock import MagicMock
+from unittest.mock import AsyncMock, MagicMock
import pytest
+from free_claude_code.messaging.models import MessageScope
from free_claude_code.messaging.trees import MessageState
from free_claude_code.messaging.workflow import MessagingWorkflow
+_SCOPE = MessageScope(platform="telegram", chat_id="chat_1")
+
@pytest.fixture
def handler_integration(mock_platform, mock_cli_manager, mock_session_store):
- # Use real TreeQueueManager
- handler = MessagingWorkflow(mock_platform, mock_cli_manager, mock_session_store)
- return handler
+ return MessagingWorkflow(mock_platform, mock_cli_manager, mock_session_store)
+
+async def _events(events):
+ for event in events:
+ yield event
-async def mock_async_gen(events):
- for e in events:
- yield e
+
+async def _wait_for_idle(handler: MessagingWorkflow) -> None:
+ for _ in range(100):
+ if handler.tree_queue.task_count() == 0:
+ return
+ await asyncio.sleep(0)
+ raise AssertionError("messaging claims did not finish")
@pytest.mark.asyncio
async def test_full_conversation_flow_single_user(
- handler_integration, mock_platform, mock_cli_manager, incoming_message_factory
-):
- # 1. First message
- msg1 = incoming_message_factory(text="message 1", message_id="m1")
- mock_platform.queue_send_message.return_value = "s1"
-
- # Mock CLI session for m1
- mock_session1 = MagicMock()
- mock_session1.start_task.return_value = mock_async_gen(
+ handler_integration,
+ mock_platform,
+ mock_cli_manager,
+ incoming_message_factory,
+) -> None:
+ mock_platform.queue_send_message = AsyncMock(side_effect=["s1", "s2"])
+ root_session = MagicMock()
+ root_session.start_task.return_value = _events(
[
{"type": "session_info", "session_id": "sess1"},
{
@@ -39,36 +47,8 @@ async def test_full_conversation_flow_single_user(
{"type": "exit", "code": 0, "stderr": None},
]
)
- mock_cli_manager.get_or_create_session.return_value = (
- mock_session1,
- "pending_1",
- True,
- )
-
- await handler_integration.handle_message(msg1)
-
- # Wait for processing
- tree = handler_integration.tree_queue.get_tree_for_node("m1")
- for _ in range(10):
- if tree.get_node("m1").state.value == MessageState.COMPLETED.value:
- break
- await asyncio.sleep(0.01)
-
- assert tree.get_node("m1").state.value == MessageState.COMPLETED.value
- assert tree.get_node("m1").session_id == "sess1"
- mock_session1.start_task.assert_called_with(
- "message 1", session_id=None, fork_session=False
- )
-
- # 2. Reply to m1
- msg2 = incoming_message_factory(
- text="message 2", message_id="m2", reply_to_message_id="m1"
- )
- mock_platform.queue_send_message.return_value = "s2"
-
- # Mock CLI session for m2
- mock_session2 = MagicMock()
- mock_session2.start_task.return_value = mock_async_gen(
+ reply_session = MagicMock()
+ reply_session.start_task.return_value = _events(
[
{"type": "session_info", "session_id": "sess2"},
{
@@ -78,110 +58,106 @@ async def test_full_conversation_flow_single_user(
{"type": "exit", "code": 0, "stderr": None},
]
)
- mock_cli_manager.get_or_create_session.reset_mock()
- mock_cli_manager.get_or_create_session.return_value = (
- mock_session2,
- "pending_2",
- True,
- )
-
- await handler_integration.handle_message(msg2)
-
- # Wait for processing
- for _ in range(10):
- if tree.get_node("m2").state.value == MessageState.COMPLETED.value:
- break
- await asyncio.sleep(0.01)
+ mock_cli_manager.get_or_create_session.side_effect = [
+ (root_session, "pending_1", True),
+ (reply_session, "pending_2", True),
+ ]
- assert tree.get_node("m2").state.value == MessageState.COMPLETED.value
- assert tree.get_node("m2").parent_id == "m1"
+ await handler_integration.handle_message(
+ incoming_message_factory(text="message 1", message_id="m1")
+ )
+ await _wait_for_idle(handler_integration)
+ root = await handler_integration.tree_queue.get_node(_SCOPE, "m1")
+ assert root is not None
+ assert root.state is MessageState.COMPLETED
+ assert root.session_id == "sess1"
+
+ await handler_integration.handle_message(
+ incoming_message_factory(
+ text="message 2",
+ message_id="m2",
+ reply_to_message_id="m1",
+ )
+ )
+ await _wait_for_idle(handler_integration)
+ reply = await handler_integration.tree_queue.get_node(_SCOPE, "m2")
+ assert reply is not None
+ assert reply.state is MessageState.COMPLETED
+ assert reply.parent_id == "m1"
mock_cli_manager.get_or_create_session.assert_called_with(session_id="sess1")
- mock_session2.start_task.assert_called_with(
+ reply_session.start_task.assert_called_with(
"message 2", session_id="sess1", fork_session=True
)
@pytest.mark.asyncio
async def test_error_propagation_chain(
- handler_integration, mock_platform, mock_cli_manager, incoming_message_factory
-):
- msg1 = incoming_message_factory(text="m1", message_id="m1")
- mock_platform.queue_send_message.return_value = "s1"
-
- mock_session1 = MagicMock()
- mock_session1.start_task.return_value = mock_async_gen(
- [{"type": "error", "error": {"message": "failed"}}]
+ handler_integration,
+ mock_platform,
+ mock_cli_manager,
+ incoming_message_factory,
+) -> None:
+ started = asyncio.Event()
+ release_error = asyncio.Event()
+
+ async def failing_events():
+ started.set()
+ await release_error.wait()
+ yield {"type": "error", "error": {"message": "failed"}}
+
+ session = MagicMock()
+ session.start_task.return_value = failing_events()
+ mock_cli_manager.get_or_create_session.return_value = (session, "sess1", False)
+ mock_platform.queue_send_message = AsyncMock(side_effect=["s1", "s2"])
+
+ await handler_integration.handle_message(
+ incoming_message_factory(text="m1", message_id="m1")
)
- mock_cli_manager.get_or_create_session.return_value = (
- mock_session1,
- "sess1",
- False,
+ await started.wait()
+ await handler_integration.handle_message(
+ incoming_message_factory(text="m2", message_id="m2", reply_to_message_id="m1")
)
-
- await handler_integration.handle_message(msg1)
- tree = handler_integration.tree_queue.get_tree_for_node("m1")
-
- msg2 = incoming_message_factory(
- text="m2", message_id="m2", reply_to_message_id="m1"
+ release_error.set()
+ await _wait_for_idle(handler_integration)
+
+ root = await handler_integration.tree_queue.get_node(_SCOPE, "m1")
+ child = await handler_integration.tree_queue.get_node(_SCOPE, "m2")
+ assert root is not None and root.state is MessageState.ERROR
+ assert child is not None and child.state is MessageState.ERROR
+ rendered = "\n".join(
+ call.args[2] for call in mock_platform.queue_edit_message.call_args_list
)
- await handler_integration.handle_message(msg2)
-
- # Wait for m1 to fail
- for _ in range(20):
- if tree.get_node("m1").state.value == MessageState.ERROR.value:
- break
- await asyncio.sleep(0.01)
-
- # Give a tiny bit of time for propagation and skipping in processor
- await asyncio.sleep(0.05)
-
- assert tree.get_node("m1").state.value == MessageState.ERROR.value
- assert tree.get_node("m2").state.value == MessageState.ERROR.value
- assert "Parent failed" in tree.get_node("m2").error_message
+ assert "Parent task failed" in rendered
@pytest.mark.asyncio
-async def test_concurrent_replies_to_different_trees(
- handler_integration, mock_platform, mock_cli_manager, incoming_message_factory
-):
- msg1 = incoming_message_factory(text="t1", message_id="t1")
- msg2 = incoming_message_factory(text="t2", message_id="t2")
-
- mock_session1 = MagicMock()
- mock_session1.start_task.return_value = mock_async_gen(
- [{"type": "exit", "code": 0}]
- )
- mock_session2 = MagicMock()
- mock_session2.start_task.return_value = mock_async_gen(
- [{"type": "exit", "code": 0}]
- )
-
+async def test_different_trees_process_independently(
+ handler_integration,
+ mock_platform,
+ mock_cli_manager,
+ incoming_message_factory,
+) -> None:
+ session_one = MagicMock()
+ session_one.start_task.return_value = _events([{"type": "exit", "code": 0}])
+ session_two = MagicMock()
+ session_two.start_task.return_value = _events([{"type": "exit", "code": 0}])
mock_cli_manager.get_or_create_session.side_effect = [
- (mock_session1, "s1", False),
- (mock_session2, "s2", False),
+ (session_one, "s1", False),
+ (session_two, "s2", False),
]
-
- await handler_integration.handle_message(msg1)
- await handler_integration.handle_message(msg2)
-
- # Wait for both
- for _ in range(20):
- node1 = handler_integration.tree_queue.get_node("t1")
- node2 = handler_integration.tree_queue.get_node("t2")
- if (
- node1
- and node2
- and node1.state.value == MessageState.COMPLETED.value
- and node2.state.value == MessageState.COMPLETED.value
- ):
- break
- await asyncio.sleep(0.01)
-
- assert (
- handler_integration.tree_queue.get_node("t1").state.value
- == MessageState.COMPLETED.value
- )
- assert (
- handler_integration.tree_queue.get_node("t2").state.value
- == MessageState.COMPLETED.value
+ mock_platform.queue_send_message = AsyncMock(side_effect=["status-t1", "status-t2"])
+
+ await asyncio.gather(
+ handler_integration.handle_message(
+ incoming_message_factory(text="t1", message_id="t1")
+ ),
+ handler_integration.handle_message(
+ incoming_message_factory(text="t2", message_id="t2")
+ ),
)
+ await _wait_for_idle(handler_integration)
+
+ node_one = await handler_integration.tree_queue.get_node(_SCOPE, "t1")
+ node_two = await handler_integration.tree_queue.get_node(_SCOPE, "t2")
+ assert node_one is not None and node_one.state is MessageState.COMPLETED
+ assert node_two is not None and node_two.state is MessageState.COMPLETED
diff --git a/tests/messaging/test_handler_markdown_and_status_edges.py b/tests/messaging/test_handler_markdown_and_status_edges.py
index 6c23bf6d..41298cb8 100644
--- a/tests/messaging/test_handler_markdown_and_status_edges.py
+++ b/tests/messaging/test_handler_markdown_and_status_edges.py
@@ -3,19 +3,59 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-from free_claude_code.messaging.models import IncomingMessage
+from free_claude_code.messaging.models import IncomingMessage, MessageScope
from free_claude_code.messaging.node_event_pipeline import process_parsed_cli_event
from free_claude_code.messaging.rendering.telegram_markdown import (
render_markdown_to_mdv2,
)
from free_claude_code.messaging.trees import (
+ CancellationReason,
+ CancellationResult,
CancellationUiOwner,
- CancelledNode,
- MessageNode,
- MessageState,
+ FailureResult,
+ NodeClaim,
+ NodeUiTarget,
+ QueueDecision,
+ QueueEntry,
+ ReplyTarget,
+ TreeIdentity,
+ TreeSnapshot,
)
+from free_claude_code.messaging.trees.transitions import CancellationEffect
from free_claude_code.messaging.workflow import MessagingWorkflow
+_SCOPE = MessageScope(platform="telegram", chat_id="c")
+
+
+def _claim() -> NodeClaim:
+ return NodeClaim(
+ identity=TreeIdentity(scope=_SCOPE, root_id="root"),
+ claim_id="claim-1",
+ node=NodeUiTarget(
+ scope=_SCOPE,
+ node_id="n1",
+ status_message_id="s1",
+ ),
+ prompt="hi",
+ parent_session_id=None,
+ )
+
+
+def _snapshot(marker: str) -> TreeSnapshot:
+ return TreeSnapshot(
+ scope=_SCOPE,
+ root_id="root",
+ nodes={"root": {"marker": marker}},
+ )
+
+
+def _decision(*, position: int | None = None) -> QueueDecision:
+ return QueueDecision(
+ claim=_claim() if position is None else None,
+ position=position,
+ snapshot=_snapshot("admitted"),
+ )
+
def test_render_markdown_to_mdv2_empty_returns_empty():
assert render_markdown_to_mdv2("") == ""
@@ -89,28 +129,23 @@ def test_get_initial_status_branches():
session_store = MagicMock()
handler = MessagingWorkflow(platform, cli_manager, session_store)
- with (
- patch.object(
- handler.tree_queue, "is_node_tree_busy", MagicMock(return_value=True)
- ),
- patch.object(handler.tree_queue, "get_queue_size", MagicMock(return_value=2)),
- ):
- s1 = handler.turn_intake._get_initial_status(tree=object(), parent_node_id="p")
+ s1 = handler.turn_intake._get_initial_status(
+ ReplyTarget(node_id="p", queue_position=3)
+ )
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.turn_intake._get_initial_status(tree=object(), parent_node_id="p")
+ s2 = handler.turn_intake._get_initial_status(
+ ReplyTarget(node_id="p", queue_position=None)
+ )
assert "Continuing" in s2
- s3 = handler.turn_intake._get_initial_status(tree=None, parent_node_id=None)
+ s3 = handler.turn_intake._get_initial_status(None)
assert "Launching" in s3
@pytest.mark.asyncio
-async def test_update_queue_positions_handles_snapshot_error_and_skips_non_pending():
+async def test_update_queue_positions_renders_immutable_queue_entries():
platform = MagicMock()
platform.queue_edit_message = AsyncMock()
platform.fire_and_forget = MagicMock(
@@ -121,26 +156,23 @@ async def test_update_queue_positions_handles_snapshot_error_and_skips_non_pendi
session_store = MagicMock()
handler = MessagingWorkflow(platform, cli_manager, session_store)
- # Snapshot error is swallowed.
- tree = MagicMock()
- tree.get_queue_snapshot = AsyncMock(side_effect=RuntimeError("boom"))
- await handler.update_queue_positions(tree)
+ await handler.turn_intake.update_queue_positions(())
platform.fire_and_forget.assert_not_called()
- # Normal path: only PENDING nodes get an update.
- node_pending = MagicMock()
- node_pending.state = MessageState.PENDING
- node_pending.incoming.chat_id = "c"
- node_pending.status_message_id = "s"
-
- node_done = MagicMock()
- node_done.state = MessageState.COMPLETED
-
- tree.get_queue_snapshot = AsyncMock(return_value=["n1", "n2"])
- tree.get_node = MagicMock(side_effect=[node_pending, node_done])
-
- await handler.update_queue_positions(tree)
+ await handler.turn_intake.update_queue_positions(
+ (
+ QueueEntry(
+ node=NodeUiTarget(
+ scope=_SCOPE,
+ node_id="n1",
+ status_message_id="s",
+ ),
+ position=2,
+ ),
+ )
+ )
assert platform.fire_and_forget.call_count == 1
+ assert "position 2" in platform.queue_edit_message.call_args.args[2]
@pytest.mark.asyncio
@@ -158,26 +190,23 @@ async def test_node_runner_process_node_session_limit_marks_error_and_updates_ui
session_store = MagicMock()
handler = MessagingWorkflow(platform, cli_manager, session_store)
- fake_tree = MagicMock()
- fake_tree.root_id = "root"
- fake_tree.snapshot = MagicMock(return_value={"root": "error"})
- fake_tree.update_state = AsyncMock()
+ claim = _claim()
+ snapshot = _snapshot("error")
+ fail_claim = AsyncMock(
+ return_value=FailureResult(affected=(), queue_update=None, snapshot=snapshot)
+ )
with patch.object(
- handler.tree_queue, "get_tree_for_node", MagicMock(return_value=fake_tree)
+ handler.tree_queue,
+ "fail_claim",
+ fail_claim,
):
- 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)
+ await handler.node_runner.process_node(claim)
assert platform.queue_edit_message.await_count >= 1
- fake_tree.update_state.assert_awaited()
- session_store.save_tree_snapshot.assert_called_once_with({"root": "error"})
+ fail_claim.assert_awaited_once_with(
+ claim,
+ propagate=False,
+ )
+ session_store.save_tree_snapshot.assert_called_once_with(snapshot)
@pytest.mark.asyncio
@@ -204,28 +233,23 @@ async def test_node_runner_cancellation_marks_error_and_saves_tree():
session_store = MagicMock()
handler = MessagingWorkflow(platform, cli_manager, session_store)
- fake_tree = MagicMock()
- fake_tree.root_id = "root"
- fake_tree.snapshot = MagicMock(return_value={"root": "cancelled"})
- fake_tree.update_state = AsyncMock()
+ claim = _claim()
+ snapshot = _snapshot("cancelled")
+ fail_claim = AsyncMock(
+ return_value=FailureResult(affected=(), queue_update=None, snapshot=snapshot)
+ )
with patch.object(
- handler.tree_queue, "get_tree_for_node", MagicMock(return_value=fake_tree)
+ handler.tree_queue,
+ "fail_claim",
+ fail_claim,
):
- 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)
+ await handler.node_runner.process_node(claim)
- fake_tree.update_state.assert_any_await(
- "n1", MessageState.ERROR, error_message="Cancelled by user"
+ fail_claim.assert_awaited_once_with(
+ claim,
+ propagate=False,
)
- session_store.save_tree_snapshot.assert_called_once_with({"root": "cancelled"})
+ session_store.save_tree_snapshot.assert_called_once_with(snapshot)
@pytest.mark.asyncio
@@ -243,36 +267,31 @@ async def test_stop_all_tasks_saves_tree_for_cancelled_nodes():
session_store = MagicMock()
handler = MessagingWorkflow(platform, cli_manager, session_store)
- 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")
-
- tree = MagicMock()
- tree.root_id = "root"
- tree.snapshot = MagicMock(return_value={"root": "ok"})
- with (
- patch.object(
- handler.tree_queue,
- "cancel_all",
- AsyncMock(return_value=[CancelledNode(node, CancellationUiOwner.RUNNER)]),
- ),
- patch.object(
- handler.tree_queue, "get_tree_for_node", MagicMock(return_value=tree)
+ snapshot = _snapshot("ok")
+ result = CancellationResult(
+ effects=(
+ CancellationEffect(
+ node=_claim().node,
+ ui_owner=CancellationUiOwner.RUNNER,
+ ),
),
+ snapshots=(snapshot,),
+ )
+ cancel_all = AsyncMock(return_value=result)
+ with patch.object(
+ handler.tree_queue,
+ "cancel_all",
+ cancel_all,
):
count = await handler.stop_all_tasks()
assert count == 1
+ cancel_all.assert_awaited_once_with(reason=CancellationReason.STOP)
cli_manager.stop_all.assert_awaited_once()
- session_store.save_tree_snapshot.assert_called_once_with({"root": "ok"})
+ session_store.save_tree_snapshot.assert_called_once_with(snapshot)
@pytest.mark.asyncio
-async def test_handle_message_reply_with_tree_but_no_parent_treated_as_new():
+async def test_handle_message_unresolved_reply_is_admitted_as_new():
platform = MagicMock()
platform.queue_send_message = AsyncMock(return_value="status_1")
platform.queue_edit_message = AsyncMock()
@@ -283,18 +302,8 @@ async def test_handle_message_reply_with_tree_but_no_parent_treated_as_new():
session_store = MagicMock()
handler = MessagingWorkflow(platform, cli_manager, session_store)
- # Force "tree exists but parent can't be resolved" branch.
- mock_queue = MagicMock()
- mock_queue.get_tree_for_node.return_value = object()
- mock_queue.resolve_parent_node_id.return_value = None
- mock_queue.create_tree = AsyncMock(
- return_value=MagicMock(
- root_id="root", snapshot=MagicMock(return_value={"t": 1})
- )
- )
- mock_queue.register_node = MagicMock()
- mock_queue.enqueue = AsyncMock(return_value=False)
- handler.replace_tree_queue(mock_queue)
+ resolve_reply = AsyncMock(return_value=None)
+ admit = AsyncMock(return_value=_decision())
incoming = IncomingMessage(
text="reply",
@@ -305,8 +314,18 @@ async def test_handle_message_reply_with_tree_but_no_parent_treated_as_new():
reply_to_message_id="some_reply",
)
- await handler.handle_message(incoming)
- mock_queue.create_tree.assert_awaited_once()
+ with (
+ patch.object(handler.tree_queue, "resolve_reply", resolve_reply),
+ patch.object(handler.tree_queue, "admit", admit),
+ ):
+ await handler.handle_message(incoming)
+
+ resolve_reply.assert_awaited_once_with(incoming.scope, "some_reply")
+ admit.assert_awaited_once_with(
+ incoming,
+ "status_1",
+ parent_node_id=None,
+ )
@pytest.mark.asyncio
@@ -338,28 +357,25 @@ async def test_update_ui_handles_transcript_render_exception():
cli_manager.get_stats.return_value = {"active_sessions": 0}
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)
+ claim = _claim()
+ snapshot = _snapshot("complete")
- 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")
-
- with patch.object(
- handler.node_runner, "_create_transcript_and_render_ctx"
- ) as mock_create:
+ with (
+ patch.object(
+ handler.node_runner, "_create_transcript_and_render_ctx"
+ ) as mock_create,
+ patch.object(
+ handler.tree_queue,
+ "complete_claim",
+ AsyncMock(return_value=snapshot),
+ ),
+ ):
transcript = MagicMock()
transcript.render = MagicMock(side_effect=ValueError("render failed"))
render_ctx = MagicMock()
mock_create.return_value = (transcript, render_ctx)
- await handler.node_runner.process_node("n1", node)
+ await handler.node_runner.process_node(claim)
assert transcript.render.call_count >= 1
@@ -376,17 +392,7 @@ async def test_handle_message_incoming_text_none_safe():
session_store = MagicMock()
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
- mock_queue.create_tree = AsyncMock(
- return_value=MagicMock(
- root_id="root", snapshot=MagicMock(return_value={"t": 1})
- )
- )
- mock_queue.register_node = MagicMock()
- mock_queue.enqueue = AsyncMock(return_value=True)
- handler.replace_tree_queue(mock_queue)
+ admit = AsyncMock(return_value=_decision())
incoming = MagicMock()
incoming.text = None
@@ -395,10 +401,17 @@ async def test_handle_message_incoming_text_none_safe():
incoming.message_id = "m1"
incoming.platform = "telegram"
incoming.reply_to_message_id = None
+ incoming.status_message_id = None
+ incoming.message_thread_id = None
incoming.is_reply = MagicMock(return_value=False)
- await handler.handle_message(incoming)
- mock_queue.create_tree.assert_awaited_once()
+ with patch.object(handler.tree_queue, "admit", admit):
+ await handler.handle_message(incoming)
+ admit.assert_awaited_once_with(
+ incoming,
+ "status_1",
+ parent_node_id=None,
+ )
@pytest.mark.asyncio
@@ -413,6 +426,8 @@ async def test_process_parsed_event_malformed_content_continues():
transcript = MagicMock()
update_ui = AsyncMock()
+ complete_claim = AsyncMock()
+ fail_claim = AsyncMock()
last_status, had = await process_parsed_cli_event(
parsed={"type": "unknown_type"},
@@ -420,15 +435,16 @@ async def test_process_parsed_event_malformed_content_continues():
update_ui=update_ui,
last_status=None,
had_transcript_events=False,
- tree=None,
- node_id="n1",
+ claim=_claim(),
captured_session_id=None,
- session_store=session_store,
format_status=handler.format_status,
- propagate_error_to_children=AsyncMock(),
+ complete_claim=complete_claim,
+ fail_claim=fail_claim,
)
assert last_status is None
assert had is False
+ complete_claim.assert_not_awaited()
+ fail_claim.assert_not_awaited()
@pytest.mark.asyncio
@@ -443,8 +459,8 @@ async def test_process_parsed_event_failed_complete_does_not_mark_success():
transcript = MagicMock()
update_ui = AsyncMock()
- tree = MagicMock()
- tree.update_state = AsyncMock()
+ complete_claim = AsyncMock()
+ fail_claim = AsyncMock()
last_status, had = await process_parsed_cli_event(
parsed={"type": "complete", "status": "failed"},
@@ -452,18 +468,18 @@ async def test_process_parsed_event_failed_complete_does_not_mark_success():
update_ui=update_ui,
last_status="❌ Error",
had_transcript_events=True,
- tree=tree,
- node_id="n1",
+ claim=_claim(),
captured_session_id="session_1",
- session_store=session_store,
format_status=handler.format_status,
- propagate_error_to_children=AsyncMock(),
+ complete_claim=complete_claim,
+ fail_claim=fail_claim,
)
assert last_status == "❌ Error"
assert had is True
update_ui.assert_not_awaited()
- tree.update_state.assert_not_awaited()
+ complete_claim.assert_not_awaited()
+ fail_claim.assert_not_awaited()
@pytest.mark.asyncio
@@ -501,19 +517,12 @@ async def test_handler_update_ui_edit_failure_does_not_crash():
session_store = MagicMock()
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)
-
- 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)
+ snapshot = _snapshot("complete")
+ with patch.object(
+ handler.tree_queue,
+ "complete_claim",
+ AsyncMock(return_value=snapshot),
+ ):
+ await handler.node_runner.process_node(_claim())
cli_manager.remove_session.assert_awaited_once()
diff --git a/tests/messaging/test_message_tree_transitions.py b/tests/messaging/test_message_tree_transitions.py
new file mode 100644
index 00000000..4e3d4475
--- /dev/null
+++ b/tests/messaging/test_message_tree_transitions.py
@@ -0,0 +1,205 @@
+import asyncio
+from dataclasses import FrozenInstanceError
+
+import pytest
+
+from free_claude_code.messaging.models import MessageScope
+from free_claude_code.messaging.trees.node import MessageNode, MessageState
+from free_claude_code.messaging.trees.runtime import MessageTree
+
+_SCOPE = MessageScope(platform="telegram", chat_id="chat")
+
+
+def _tree() -> MessageTree:
+ return MessageTree(
+ MessageNode(
+ node_id="root",
+ scope=_SCOPE,
+ prompt="prompt root",
+ status_message_id="status-root",
+ )
+ )
+
+
+async def _add(
+ tree: MessageTree,
+ node_id: str,
+ status_message_id: str,
+ parent_id: str = "root",
+):
+ return await tree.add_and_enqueue(
+ node_id,
+ _SCOPE,
+ f"prompt {node_id}",
+ status_message_id,
+ parent_id,
+ )
+
+
+async def test_enqueue_finish_and_claim_next_are_atomic_and_fifo() -> None:
+ tree = _tree()
+
+ root = await tree.enqueue_or_claim("root")
+ child_a = await _add(tree, "child-a", "status-a")
+ child_b = await _add(tree, "child-b", "status-b")
+
+ assert root.accepted and root.claim is not None and root.position is None
+ assert child_a.claim is None and child_a.position == 1
+ assert child_b.claim is None and child_b.position == 2
+
+ completion = await tree.finish_and_claim_next(root.claim.claim_id)
+
+ assert completion.next_claim is not None
+ assert completion.next_claim.node.node_id == "child-a"
+ assert [(entry.node.node_id, entry.position) for entry in completion.queue] == [
+ ("child-b", 1)
+ ]
+
+
+async def test_duplicate_unknown_and_terminal_admission_are_rejected_without_wedge() -> (
+ None
+):
+ tree = _tree()
+
+ first = await tree.enqueue_or_claim("root")
+ duplicate = await tree.enqueue_or_claim("root")
+ unknown = await tree.enqueue_or_claim("status-root")
+ assert first.claim is not None
+ assert duplicate.accepted is False
+ assert unknown.accepted is False
+ assert duplicate.snapshot is None
+ assert unknown.snapshot is None
+
+ await tree.complete_claim(first.claim.claim_id, "session")
+ await tree.finish_and_claim_next(first.claim.claim_id)
+ terminal = await tree.enqueue_or_claim("root")
+ assert terminal.accepted is False
+ assert terminal.snapshot is None
+
+
+async def test_stale_claim_id_cannot_clear_a_newer_claim() -> None:
+ tree = _tree()
+ first = await tree.enqueue_or_claim("root")
+ assert first.claim is not None
+ await tree.finish_and_claim_next(first.claim.claim_id)
+
+ second = await _add(tree, "child", "status-child")
+ assert second.claim is not None
+
+ stale = await tree.finish_and_claim_next(first.claim.claim_id)
+ assert stale.next_claim is None
+ assert await tree.record_session(second.claim.claim_id, "session") is not None
+ await tree.finish_and_claim_next(second.claim.claim_id)
+ third = await _add(tree, "third", "status-third")
+ assert third.claim is not None
+
+
+async def test_cancellation_keeps_active_identity_until_matching_finish() -> None:
+ tree = _tree()
+ root = await tree.enqueue_or_claim("root")
+ queued = await _add(tree, "queued", "status-queued")
+ assert root.claim is not None and queued.position == 1
+
+ cancelled = await tree.cancel_node("root")
+
+ assert cancelled.active_claim == root.claim
+ assert [node.node_id for node in cancelled.nodes] == ["root"]
+
+ completion = await tree.finish_and_claim_next(root.claim.claim_id)
+ assert completion.next_claim is not None
+ assert completion.next_claim.node.node_id == "queued"
+
+
[email protected]("propagate", [False, True])
+async def test_cancelled_claim_rejects_late_failure_and_descendant_propagation(
+ propagate: bool,
+) -> None:
+ tree = _tree()
+ root = await tree.enqueue_or_claim("root")
+ queued = await _add(tree, "queued", "status-queued")
+ assert root.claim is not None and queued.position == 1
+
+ await tree.cancel_node("root")
+ late_failure = await tree.fail_claim(
+ root.claim.claim_id,
+ propagate=propagate,
+ )
+
+ assert late_failure.snapshot is None
+ assert late_failure.affected == ()
+ assert late_failure.queue_update is None
+ queued_view = await tree.node_view("queued")
+ assert queued_view is not None
+ assert queued_view.state is MessageState.PENDING
+ completion = await tree.finish_and_claim_next(root.claim.claim_id)
+ assert completion.next_claim is not None
+ assert completion.next_claim.node.node_id == "queued"
+
+
+async def test_cancelled_queue_member_is_never_claimed() -> None:
+ tree = _tree()
+ root = await tree.enqueue_or_claim("root")
+ await _add(tree, "a", "status-a")
+ await _add(tree, "b", "status-b")
+ assert root.claim is not None
+
+ cancelled = await tree.cancel_node("a")
+ assert [node.node_id for node in cancelled.nodes] == ["a"]
+
+ completion = await tree.finish_and_claim_next(root.claim.claim_id)
+ assert completion.next_claim is not None
+ assert completion.next_claim.node.node_id == "b"
+
+
+async def test_concurrent_duplicate_enqueue_produces_one_claim_only() -> None:
+ tree = _tree()
+ gate = asyncio.Event()
+
+ async def enqueue():
+ await gate.wait()
+ return await tree.enqueue_or_claim("root")
+
+ tasks = [asyncio.create_task(enqueue()) for _ in range(20)]
+ gate.set()
+ results = await asyncio.gather(*tasks)
+
+ assert sum(result.claim is not None for result in results) == 1
+ assert sum(result.accepted for result in results) == 1
+
+
+async def test_results_are_frozen_and_do_not_expose_mutable_nodes() -> None:
+ tree = _tree()
+ decision = await tree.enqueue_or_claim("root")
+ assert decision.claim is not None
+
+ with pytest.raises(FrozenInstanceError):
+ decision.claim.__setattr__("claim_id", "replacement")
+ assert not hasattr(decision.claim, "__dict__")
+ assert not isinstance(decision.claim.node, MessageNode)
+
+
+def test_message_tree_has_no_lock_or_partial_mutation_escape_hatches() -> None:
+ forbidden = {
+ "with_lock",
+ "enqueue",
+ "dequeue",
+ "put_queue_unlocked",
+ "remove_from_queue",
+ "set_processing_state",
+ "clear_current_node",
+ "set_current_task",
+ "cancel_current_task",
+ "set_node_error_sync",
+ "drain_queue_and_mark_cancelled",
+ "reset_processing_state",
+ }
+
+ assert forbidden.isdisjoint(vars(MessageTree))
diff --git a/tests/messaging/test_messaging.py b/tests/messaging/test_messaging.py
index 1d551365..65b3423e 100644
--- a/tests/messaging/test_messaging.py
+++ b/tests/messaging/test_messaging.py
@@ -1,5 +1,6 @@
"""Tests for messaging/ module."""
+import asyncio
import json
from unittest.mock import AsyncMock, MagicMock, patch
@@ -87,12 +88,15 @@ class TestSessionStore:
def test_save_and_get_tree(self, tmp_path):
"""Test saving and retrieving trees."""
+ from free_claude_code.messaging.models import MessageScope
from free_claude_code.messaging.session import SessionStore
- from free_claude_code.messaging.trees import TreeSnapshot
+ from free_claude_code.messaging.trees import TreeIdentity, TreeSnapshot
store = SessionStore(storage_path=str(tmp_path / "sessions.json"))
+ scope = MessageScope(platform="telegram", chat_id="chat")
tree_data = {
+ "scope": {"platform": scope.platform, "chat_id": scope.chat_id},
"root_id": "r1",
"nodes": {
"r1": {"node_id": "r1", "status_message_id": "s1"},
@@ -103,22 +107,36 @@ class TestSessionStore:
assert snapshot is not None
store.save_tree_snapshot(snapshot)
- loaded = store.get_tree_snapshot("r1")
+ identity = TreeIdentity(scope=scope, root_id="r1")
+ loaded = store.load_conversation_snapshot().get_tree(identity)
+ assert loaded is not None
assert loaded == snapshot
-
- node_map = store.load_conversation_snapshot().derive_node_to_tree()
- assert node_map["r1"] == "r1"
- assert node_map["n1"] == "r1"
+ assert loaded.lookup_ids() == {"r1", "s1", "n1", "s2"}
# --- Persistence & Edge Cases ---
def test_load_existing_file_with_trees(self, tmp_path):
"""Test loading file with trees (legacy sessions ignored)."""
+ from free_claude_code.messaging.models import MessageScope
from free_claude_code.messaging.session import SessionStore
+ from free_claude_code.messaging.trees import TreeIdentity
data = {
"sessions": {},
- "trees": {"r1": {"root_id": "r1", "nodes": {"r1": {}}}},
+ "trees": {
+ "r1": {
+ "root_id": "r1",
+ "nodes": {
+ "r1": {
+ "node_id": "r1",
+ "incoming": {
+ "platform": "telegram",
+ "chat_id": "chat",
+ },
+ }
+ },
+ }
+ },
"node_to_tree": {"r1": "r1"},
"message_log": {},
}
@@ -128,7 +146,11 @@ class TestSessionStore:
json.dump(data, f)
store = SessionStore(storage_path=str(p))
- assert store.get_tree_snapshot("r1") is not None
+ identity = TreeIdentity(
+ scope=MessageScope(platform="telegram", chat_id="chat"),
+ root_id="r1",
+ )
+ assert store.load_conversation_snapshot().get_tree(identity) is not None
def test_load_corrupt_file(self, tmp_path):
"""Test loading corrupt/invalid json file."""
@@ -144,11 +166,13 @@ class TestSessionStore:
def test_save_error_handling(self, tmp_path):
"""Test error during save."""
+ from free_claude_code.messaging.models import MessageScope
from free_claude_code.messaging.session import SessionStore
- from free_claude_code.messaging.trees import TreeSnapshot
+ from free_claude_code.messaging.trees import TreeIdentity, TreeSnapshot
store = SessionStore(storage_path=str(tmp_path / "sessions.json"))
- snapshot = TreeSnapshot(root_id="r1", nodes={"r1": {}})
+ scope = MessageScope(platform="telegram", chat_id="chat")
+ snapshot = TreeSnapshot(scope=scope, root_id="r1", nodes={"r1": {}})
store.save_tree_snapshot(snapshot)
with patch(
@@ -158,60 +182,57 @@ class TestSessionStore:
store.flush_pending_save()
assert store.dirty is True
- assert store.get_tree_snapshot("r1") is not None
+ identity = TreeIdentity(scope=scope, root_id="r1")
+ assert store.load_conversation_snapshot().get_tree(identity) is not None
class TestTreeQueueManager:
"""Test TreeQueueManager."""
def test_tree_queue_manager_init(self):
- """Test TreeQueueManager initialization."""
from free_claude_code.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 free_claude_code.messaging.trees import TreeQueueManager
+ async def process(_claim):
+ return None
- 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 free_claude_code.messaging.trees import TreeQueueManager
-
- mgr = TreeQueueManager()
- assert mgr.get_queue_size("nonexistent") == 0
+ mgr = TreeQueueManager(process)
+ assert mgr.get_tree_count() == 0
@pytest.mark.asyncio
- async def test_create_tree_and_enqueue(self):
- """Test creating a tree and enqueueing."""
+ async def test_admit_creates_tree_and_claim(self):
from free_claude_code.messaging.models import IncomingMessage
from free_claude_code.messaging.trees import TreeQueueManager
- mgr = TreeQueueManager()
- processed = []
+ processed = asyncio.Event()
- async def processor(node_id, node):
- processed.append(node_id)
+ async def processor(claim):
+ assert claim.node.node_id == "1"
+ processed.set()
incoming = IncomingMessage(
- text="test", chat_id="1", user_id="1", message_id="1", platform="test"
+ text="test",
+ chat_id="1",
+ user_id="1",
+ message_id="1",
+ platform="test",
)
- await mgr.create_tree("1", incoming, "status_1")
- was_queued = await mgr.enqueue("1", processor)
+ mgr = TreeQueueManager(processor)
+ decision = await mgr.admit(incoming, "status_1")
- # First message should process immediately, not queue
- assert was_queued is False
+ assert decision.accepted is True
+ assert decision.claim is not None
+ await processed.wait()
@pytest.mark.asyncio
- async def test_cancel_tree_empty(self):
- """Test cancelling non-existent tree."""
+ async def test_cancel_unknown_node_is_empty(self):
+ from free_claude_code.messaging.models import MessageScope
from free_claude_code.messaging.trees import TreeQueueManager
- mgr = TreeQueueManager()
- cancelled = await mgr.cancel_tree("nonexistent")
- assert cancelled == []
+ async def process(_claim):
+ return None
+
+ mgr = TreeQueueManager(process)
+ scope = MessageScope(platform="test", chat_id="1")
+ cancelled = await mgr.cancel_node(scope, "nonexistent")
+ assert cancelled.effects == ()
diff --git a/tests/messaging/test_platform_voice_flow.py b/tests/messaging/test_platform_voice_flow.py
index dc5070fb..db69b2ea 100644
--- a/tests/messaging/test_platform_voice_flow.py
+++ b/tests/messaging/test_platform_voice_flow.py
@@ -4,6 +4,7 @@ from unittest.mock import AsyncMock
import pytest
+from free_claude_code.messaging.models import MessageScope
from free_claude_code.messaging.platforms.voice_flow import (
VOICE_DISABLED_MESSAGE,
VOICE_TRANSCRIPTION_ERROR_MESSAGE,
@@ -14,6 +15,8 @@ from free_claude_code.messaging.platforms.voice_flow import (
)
from free_claude_code.messaging.voice import Transcriber
+VOICE_SCOPE = MessageScope(platform="telegram", chat_id="chat")
+
class MockTranscriber:
def __init__(self, result: str = "hello from voice") -> None:
@@ -101,7 +104,6 @@ async def test_voice_flow_success_builds_incoming_message() -> None:
incoming = handler.call_args.args[0]
assert incoming.text == "hello from voice"
assert incoming.chat_id == "chat"
- assert incoming.user_id == "user"
assert incoming.message_id == "voice"
assert incoming.reply_to_message_id == "reply"
assert incoming.message_thread_id == "thread"
@@ -133,7 +135,7 @@ async def test_voice_flow_cancelled_transcription_deletes_status() -> None:
flow, transcriber = _flow()
async def canceling_transcribe(_path: Path) -> str:
- await flow.cancel_pending_voice("chat", "voice")
+ await flow.cancel_pending_voice(VOICE_SCOPE, "voice")
return "ignored"
transcriber.run.side_effect = canceling_transcribe
@@ -189,7 +191,7 @@ async def test_voice_flow_task_cancellation_waits_then_cleans_pending_state() ->
await cancellation_received.wait()
assert not handle_task.done()
- assert await flow.is_voice_still_pending("chat", "voice") is True
+ assert await flow.is_voice_still_pending(VOICE_SCOPE, "voice") is True
queue_delete.assert_not_awaited()
release.set()
@@ -199,7 +201,7 @@ async def test_voice_flow_task_cancellation_waits_then_cleans_pending_state() ->
assert stopped.is_set()
handler.assert_not_awaited()
queue_delete.assert_awaited_once_with("chat", ["status"])
- assert await flow.cancel_pending_voice("chat", "voice") is None
+ assert await flow.cancel_pending_voice(VOICE_SCOPE, "voice") is None
@pytest.mark.asyncio
@@ -222,7 +224,7 @@ async def test_voice_flow_download_failure_cleans_pending_state() -> None:
transcriber.run.assert_not_awaited()
queue_delete.assert_awaited_once_with("chat", ["status"])
reply_text.assert_awaited_once_with(VOICE_TRANSCRIPTION_ERROR_MESSAGE)
- assert await flow.cancel_pending_voice("chat", "voice") is None
+ assert await flow.cancel_pending_voice(VOICE_SCOPE, "voice") is None
@pytest.mark.asyncio
@@ -242,7 +244,7 @@ async def test_voice_flow_transcription_failure_cleans_pending_state() -> None:
assert handled is True
queue_delete.assert_awaited_once_with("chat", ["status"])
reply_text.assert_awaited_once_with(VOICE_TRANSCRIPTION_ERROR_MESSAGE)
- assert await flow.cancel_pending_voice("chat", "voice") is None
+ assert await flow.cancel_pending_voice(VOICE_SCOPE, "voice") is None
@pytest.mark.asyncio
@@ -266,7 +268,7 @@ async def test_voice_flow_handler_failure_cleans_pending_without_deleting_status
assert handled is True
queue_delete.assert_not_awaited()
reply_text.assert_awaited_once_with(VOICE_TRANSCRIPTION_ERROR_MESSAGE)
- assert await flow.cancel_pending_voice("chat", "voice") is None
+ assert await flow.cancel_pending_voice(VOICE_SCOPE, "voice") is None
@pytest.mark.asyncio
diff --git a/tests/messaging/test_restart_reply_restore.py b/tests/messaging/test_restart_reply_restore.py
index c8396a07..8ddc0a3e 100644
--- a/tests/messaging/test_restart_reply_restore.py
+++ b/tests/messaging/test_restart_reply_restore.py
@@ -1,173 +1,286 @@
-from unittest.mock import AsyncMock, patch
+import asyncio
+import json
+from unittest.mock import AsyncMock, MagicMock
import pytest
-from free_claude_code.messaging.models import IncomingMessage
+from free_claude_code.messaging.models import IncomingMessage, MessageScope
from free_claude_code.messaging.session import SessionStore
-from free_claude_code.messaging.trees import TreeQueueManager
+from free_claude_code.messaging.trees import TreeIdentity
+from free_claude_code.messaging.trees.node import MessageNode, MessageState
+from free_claude_code.messaging.trees.runtime import MessageTree
from free_claude_code.messaging.workflow import MessagingWorkflow
+TELEGRAM_CHAT_1 = MessageScope(platform="telegram", chat_id="chat_1")
-async def test_reply_to_old_status_message_after_restore_routes_to_parent(
- tmp_path, mock_platform, mock_cli_manager
-):
- # Build a persisted tree with a root node A and a bot status message id.
- store_path = tmp_path / "sessions.json"
- store = SessionStore(storage_path=str(store_path))
- handler1 = MessagingWorkflow(mock_platform, mock_cli_manager, store)
- a_incoming = IncomingMessage(
- text="A",
- chat_id="chat_1",
- user_id="user_1",
- message_id="A",
- platform="telegram",
- )
- tree = await handler1.tree_queue.create_tree(
- "A", a_incoming, status_message_id="status_A"
+async def _wait_for_idle(workflow: MessagingWorkflow) -> None:
+ for _ in range(100):
+ if workflow.tree_queue.task_count() == 0:
+ return
+ await asyncio.sleep(0)
+ raise AssertionError("messaging claims did not finish")
+
+
+async def _write_completed_root(store: SessionStore) -> None:
+ tree = MessageTree(
+ MessageNode(
+ node_id="A",
+ scope=TELEGRAM_CHAT_1,
+ prompt="A",
+ status_message_id="status_A",
+ state=MessageState.COMPLETED,
+ session_id="sess_A",
+ )
)
- handler1.tree_queue.register_node("status_A", tree.root_id)
- store.save_tree_snapshot(tree.snapshot())
+ store.save_tree_snapshot(await tree.snapshot())
store.flush_pending_save()
- # "Restart": new store instance loads from disk, and we restore TreeQueueManager.
- store2 = SessionStore(storage_path=str(store_path))
- handler2 = MessagingWorkflow(mock_platform, mock_cli_manager, store2)
- handler2.restore()
- # Prevent background task scheduling; we only want to validate routing/tree mutation.
- mock_platform.queue_send_message = AsyncMock(return_value="status_reply")
-
- reply = IncomingMessage(
- text="R1",
- chat_id="chat_1",
- user_id="user_1",
- message_id="R1",
- platform="telegram",
- reply_to_message_id="status_A",
+async def _write_interrupted_root(store: SessionStore) -> None:
+ tree = MessageTree(
+ MessageNode(
+ node_id="A",
+ scope=TELEGRAM_CHAT_1,
+ prompt="A",
+ status_message_id="status_A",
+ state=MessageState.IN_PROGRESS,
+ )
)
+ store.save_tree_snapshot(await tree.snapshot())
+ store.flush_pending_save()
+
- with patch.object(handler2.tree_queue, "enqueue", AsyncMock(return_value=False)):
- await handler2.handle_message(reply)
+def _successful_session(session_id: str):
+ session = MagicMock()
- 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 events(*_args, **_kwargs):
+ yield {"type": "session_info", "session_id": session_id}
+ yield {"type": "exit", "code": 0, "stderr": None}
+
+ session.start_task = events
+ return session
@pytest.mark.asyncio
-async def test_save_tree_persists_status_message_mapping_without_manual_register(
- tmp_path, mock_platform, mock_cli_manager
-):
+async def test_reply_to_old_status_message_after_restore_routes_to_parent(
+ tmp_path,
+ mock_platform,
+ mock_cli_manager,
+) -> None:
store_path = tmp_path / "sessions.json"
- store = SessionStore(storage_path=str(store_path))
+ await _write_completed_root(SessionStore(storage_path=str(store_path)))
- handler1 = MessagingWorkflow(mock_platform, mock_cli_manager, store)
- a_incoming = IncomingMessage(
- text="A",
- chat_id="chat_1",
- user_id="user_1",
- message_id="A",
- platform="telegram",
+ restored_store = SessionStore(storage_path=str(store_path))
+ workflow = MessagingWorkflow(mock_platform, mock_cli_manager, restored_store)
+ workflow.restore()
+ mock_platform.queue_send_message = AsyncMock(return_value="status_reply")
+ mock_cli_manager.get_or_create_session.return_value = (
+ _successful_session("sess_R1"),
+ "pending_R1",
+ True,
)
- tree = await handler1.tree_queue.create_tree(
- "A", a_incoming, status_message_id="status_A"
+
+ await workflow.handle_message(
+ IncomingMessage(
+ text="R1",
+ chat_id="chat_1",
+ user_id="user_1",
+ message_id="R1",
+ platform="telegram",
+ reply_to_message_id="status_A",
+ )
)
- store.save_tree_snapshot(tree.snapshot())
- store.flush_pending_save()
+ await _wait_for_idle(workflow)
+
+ reply = await workflow.tree_queue.get_node(TELEGRAM_CHAT_1, "R1")
+ assert reply is not None
+ assert reply.parent_id == "A"
+ mock_cli_manager.get_or_create_session.assert_called_with(session_id="sess_A")
+
- store2 = SessionStore(storage_path=str(store_path))
- handler2 = MessagingWorkflow(mock_platform, mock_cli_manager, store2)
- handler2.restore()
[email protected]("wrapped", [False, True])
+async def test_legacy_session_json_restores_through_workflow_and_routes_reply(
+ wrapped: bool,
+ tmp_path,
+ mock_platform,
+ mock_cli_manager,
+) -> None:
+ legacy_tree = {
+ "root_id": "A",
+ "nodes": {
+ "A": {
+ "node_id": "A",
+ "incoming": {
+ "text": "legacy prompt",
+ "chat_id": "chat_1",
+ "user_id": "legacy-user",
+ "message_id": "A",
+ "platform": "telegram",
+ },
+ "status_message_id": "status_A",
+ "state": "completed",
+ "parent_id": None,
+ "session_id": "sess_A",
+ "children_ids": [],
+ "created_at": "2025-01-01T00:00:00+00:00",
+ "completed_at": "2025-01-01T00:00:01+00:00",
+ "error_message": None,
+ }
+ },
+ }
+ conversation = {"trees": {"A": legacy_tree}}
+ payload = (
+ {"conversation": conversation, "message_log": {}}
+ if wrapped
+ else {
+ **conversation,
+ "node_to_tree": {"A": "A"},
+ "message_log": {},
+ }
+ )
+ store_path = tmp_path / "sessions.json"
+ store_path.write_text(json.dumps(payload), encoding="utf-8")
+ workflow = MessagingWorkflow(
+ mock_platform,
+ mock_cli_manager,
+ SessionStore(storage_path=str(store_path)),
+ )
+ workflow.restore()
mock_platform.queue_send_message = AsyncMock(return_value="status_reply")
+ mock_cli_manager.get_or_create_session.return_value = (
+ _successful_session("sess_R1"),
+ "pending_R1",
+ True,
+ )
- reply = IncomingMessage(
- text="R1",
- chat_id="chat_1",
- user_id="user_1",
- message_id="R1",
- platform="telegram",
- reply_to_message_id="status_A",
+ await workflow.handle_message(
+ IncomingMessage(
+ text="continue legacy tree",
+ chat_id="chat_1",
+ user_id="user_1",
+ message_id="R1",
+ platform="telegram",
+ reply_to_message_id="status_A",
+ )
)
+ await _wait_for_idle(workflow)
+
+ reply = await workflow.tree_queue.get_node(TELEGRAM_CHAT_1, "R1")
+ assert reply is not None and reply.parent_id == "A"
+ mock_cli_manager.get_or_create_session.assert_called_with(session_id="sess_A")
+
- with patch.object(handler2.tree_queue, "enqueue", AsyncMock(return_value=False)):
- await handler2.handle_message(reply)
+async def test_save_tree_snapshot_restores_status_lookup_without_manual_index(
+ tmp_path,
+ mock_platform,
+ mock_cli_manager,
+) -> None:
+ store_path = tmp_path / "sessions.json"
+ await _write_completed_root(SessionStore(storage_path=str(store_path)))
+ workflow = MessagingWorkflow(
+ mock_platform,
+ mock_cli_manager,
+ SessionStore(storage_path=str(store_path)),
+ )
+ workflow.restore()
- 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"
+ assert await workflow.resolve_node_id(TELEGRAM_CHAT_1, "status_A") == "A"
@pytest.mark.asyncio
async def test_reply_clear_purges_removed_status_mapping_from_persisted_store(
- tmp_path, mock_platform, mock_cli_manager
-):
+ tmp_path,
+ mock_platform,
+ mock_cli_manager,
+) -> None:
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"
+ workflow = MessagingWorkflow(mock_platform, mock_cli_manager, store)
+ mock_platform.queue_send_message = AsyncMock(
+ side_effect=["root_status", "child_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",
+ mock_cli_manager.get_or_create_session.side_effect = [
+ (_successful_session("sess_root"), "pending_root", True),
+ (_successful_session("sess_child"), "pending_child", True),
+ ]
+
+ await workflow.handle_message(
+ IncomingMessage(
+ text="root",
+ chat_id="chat_1",
+ user_id="user_1",
+ message_id="root",
+ platform="telegram",
+ )
)
- await handler.tree_queue.add_to_tree(
- "root", "child", child_incoming, status_message_id="child_status"
+ await _wait_for_idle(workflow)
+ await workflow.handle_message(
+ IncomingMessage(
+ text="child",
+ chat_id="chat_1",
+ user_id="user_1",
+ message_id="child",
+ platform="telegram",
+ reply_to_message_id="root",
+ )
)
- handler.tree_queue.register_node("child_status", tree.root_id)
- store.save_tree_snapshot(tree.snapshot())
-
- 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 _wait_for_idle(workflow)
+ await workflow.handle_message(
+ 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_snapshot(
- restored_store.load_conversation_snapshot()
- )
-
- 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
+ identity = TreeIdentity(scope=TELEGRAM_CHAT_1, root_id="root")
+ persisted = SessionStore(storage_path=str(store_path)).load_conversation_snapshot()
+ tree = persisted.get_tree(identity)
+ assert tree is not None
+ assert tree.lookup_ids() == {"root", "root_status"}
-def test_workflow_close_flushes_owned_session_store(
- mock_platform, mock_cli_manager, mock_session_store
+async def test_restore_repairs_interrupted_status_after_delivery_starts(
+ tmp_path,
+ mock_platform,
+ mock_cli_manager,
) -> None:
+ store_path = tmp_path / "sessions.json"
+ await _write_interrupted_root(SessionStore(storage_path=str(store_path)))
workflow = MessagingWorkflow(
mock_platform,
mock_cli_manager,
- mock_session_store,
+ SessionStore(storage_path=str(store_path)),
+ platform_name="telegram",
)
+ workflow.restore()
+
+ await workflow.repair_restored_statuses()
+ await workflow.repair_restored_statuses()
+
+ mock_platform.queue_edit_message.assert_awaited_once_with(
+ TELEGRAM_CHAT_1.chat_id,
+ "status_A",
+ workflow.format_status("❌", "Interrupted by server restart"),
+ parse_mode="MarkdownV2",
+ fire_and_forget=False,
+ )
+
+
+def test_workflow_close_flushes_owned_session_store(
+ mock_platform,
+ mock_cli_manager,
+ mock_session_store,
+) -> None:
+ workflow = MessagingWorkflow(mock_platform, mock_cli_manager, mock_session_store)
workflow.close()
diff --git a/tests/messaging/test_session_store_edge_cases.py b/tests/messaging/test_session_store_edge_cases.py
index e9aa6bac..fa3debab 100644
--- a/tests/messaging/test_session_store_edge_cases.py
+++ b/tests/messaging/test_session_store_edge_cases.py
@@ -1,6 +1,7 @@
"""Edge case tests for the messaging session store."""
import json
+import threading
from collections.abc import Callable
from typing import Any, ClassVar
from unittest.mock import patch
@@ -8,9 +9,16 @@ from unittest.mock import patch
import pytest
import free_claude_code.messaging.session.persistence as persistence_module
+from free_claude_code.messaging.models import MessageScope
from free_claude_code.messaging.session import SessionStore
from free_claude_code.messaging.session.persistence import DebouncedJsonPersistence
-from free_claude_code.messaging.trees import TreeSnapshot
+from free_claude_code.messaging.trees import TreeIdentity, TreeSnapshot
+
+TELEGRAM_C1 = MessageScope(platform="telegram", chat_id="c1")
+
+
+def _identity(root_id: str, scope: MessageScope = TELEGRAM_C1) -> TreeIdentity:
+ return TreeIdentity(scope=scope, root_id=root_id)
@pytest.fixture
@@ -69,7 +77,7 @@ class RecordingPersistence(DebouncedJsonPersistence):
self.writes: list[dict[str, Any]] = []
super().__init__(storage_path, snapshot=snapshot, on_dirty=on_dirty)
- def write_data(self, data: dict[str, Any]) -> None:
+ def _write_file(self, data: dict[str, Any]) -> None:
self.writes.append(data)
@@ -124,7 +132,20 @@ class TestSessionStoreLoadEdgeCases:
"updated_at": "2025-01-01T00:00:00+00:00",
}
},
- "trees": {"r1": {"root_id": "r1", "nodes": {"r1": {}}}},
+ "trees": {
+ "r1": {
+ "root_id": "r1",
+ "nodes": {
+ "r1": {
+ "node_id": "r1",
+ "incoming": {
+ "platform": TELEGRAM_C1.platform,
+ "chat_id": TELEGRAM_C1.chat_id,
+ },
+ }
+ },
+ }
+ },
"node_to_tree": {"r1": "r1"},
"message_log": {},
}
@@ -132,7 +153,7 @@ class TestSessionStoreLoadEdgeCases:
json.dump(data, f)
store = SessionStore(storage_path=path)
- assert store.get_tree_snapshot("r1") is not None
+ assert store.load_conversation_snapshot().get_tree(_identity("r1")) is not None
class TestSessionStoreSaveEdgeCases:
@@ -140,7 +161,9 @@ class TestSessionStoreSaveEdgeCases:
def test_save_io_error_handled(self, tmp_store):
"""Write failure marks pending state dirty without crashing callers."""
- tmp_store.save_tree_snapshot(TreeSnapshot(root_id="r1", nodes={"r1": {}}))
+ tmp_store.save_tree_snapshot(
+ TreeSnapshot(scope=TELEGRAM_C1, root_id="r1", nodes={"r1": {}})
+ )
with patch(
"free_claude_code.messaging.session.persistence.os.replace",
side_effect=OSError("disk full"),
@@ -181,14 +204,114 @@ class TestSessionStoreSaveEdgeCases:
assert persistence.writes == [{"snapshot": 1}]
assert dirty_states[-1] is False
+ def test_running_old_write_finishes_before_newer_flush(self, tmp_path, monkeypatch):
+ """A claimed old snapshot cannot land after a newer flushed snapshot."""
+ FakeTimer.instances = []
+ monkeypatch.setattr(persistence_module.threading, "Timer", FakeTimer)
+
+ state = {"version": "old"}
+ dirty_states: list[bool] = []
+ old_write_started = threading.Event()
+ release_old_write = threading.Event()
+
+ class BlockingPersistence(RecordingPersistence):
+ def _write_file(self, data: dict[str, Any]) -> None:
+ if data == {"version": "old"}:
+ old_write_started.set()
+ release_old_write.wait(timeout=2)
+ super()._write_file(data)
+
+ persistence = BlockingPersistence(
+ str(tmp_path / "sessions.json"),
+ snapshot=lambda: dict(state),
+ on_dirty=dirty_states.append,
+ )
+ persistence.schedule_save()
+ old_writer = threading.Thread(target=FakeTimer.instances[0].fire)
+ old_writer.start()
+ assert old_write_started.wait(timeout=2)
+
+ state["version"] = "new"
+ persistence.schedule_save()
+ new_writer = threading.Thread(target=persistence.flush)
+ new_writer.start()
+ assert new_writer.is_alive()
+
+ release_old_write.set()
+ old_writer.join(timeout=2)
+ new_writer.join(timeout=2)
+
+ assert not old_writer.is_alive()
+ assert not new_writer.is_alive()
+ assert persistence.writes == [{"version": "old"}, {"version": "new"}]
+ assert dirty_states[-1] is False
+
+
+class TestSessionStoreTreeSnapshots:
+ def test_unscoped_tree_without_legacy_ingress_is_reported_and_skipped(
+ self, tmp_path
+ ):
+ path = tmp_path / "sessions.json"
+ path.write_text(
+ json.dumps(
+ {
+ "conversation": {
+ "trees": [
+ {
+ "root_id": "root",
+ "nodes": {
+ "root": {
+ "node_id": "root",
+ "status_message_id": "status",
+ "state": "completed",
+ }
+ },
+ }
+ ]
+ }
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ with patch(
+ "free_claude_code.messaging.trees.snapshot.logger.warning"
+ ) as warning:
+ store = SessionStore(storage_path=str(path))
+
+ assert store.load_conversation_snapshot().is_empty
+ warning.assert_called_once_with(
+ "Skipping messaging tree snapshot without recoverable scope: root_id={}",
+ "root",
+ )
+
+ def test_snapshot_ingress_and_egress_are_deeply_detached(self, tmp_path):
+ store = SessionStore(storage_path=str(tmp_path / "sessions.json"))
+ snapshot = TreeSnapshot(
+ scope=TELEGRAM_C1,
+ root_id="root",
+ nodes={"root": {"node_id": "root", "state": "completed"}},
+ )
+ store.save_tree_snapshot(snapshot)
+ snapshot.nodes["root"]["state"] = "mutated-after-save"
+
+ loaded = store.load_conversation_snapshot()
+ loaded_tree = loaded.get_tree(_identity("root"))
+ assert loaded_tree is not None
+ assert loaded_tree.nodes["root"]["state"] == "completed"
+ loaded_tree.nodes["root"]["state"] = "mutated-after-load"
+
+ reloaded = store.load_conversation_snapshot().get_tree(_identity("root"))
+ assert reloaded is not None
+ assert reloaded.nodes["root"]["state"] == "completed"
-class TestSessionStoreTreeMappings:
- def test_save_tree_rebuilds_lookup_ids_for_that_root(self, tmp_path):
+ def test_save_tree_replaces_snapshot_for_scoped_identity(self, tmp_path):
path = str(tmp_path / "sessions.json")
store = SessionStore(storage_path=path)
store.save_tree_snapshot(
TreeSnapshot(
+ scope=TELEGRAM_C1,
root_id="root",
nodes={
"root": _tree_node("root", "root_status"),
@@ -197,14 +320,18 @@ class TestSessionStoreTreeMappings:
)
)
- mapping = store.load_conversation_snapshot().derive_node_to_tree()
- assert mapping["root"] == "root"
- assert mapping["root_status"] == "root"
- assert mapping["child"] == "root"
- assert mapping["child_status"] == "root"
+ saved = store.load_conversation_snapshot().get_tree(_identity("root"))
+ assert saved is not None
+ assert saved.lookup_ids() == {
+ "root",
+ "root_status",
+ "child",
+ "child_status",
+ }
store.save_tree_snapshot(
TreeSnapshot(
+ scope=TELEGRAM_C1,
root_id="root",
nodes={
"root": _tree_node("root", "root_status"),
@@ -212,17 +339,16 @@ class TestSessionStoreTreeMappings:
)
)
- mapping = store.load_conversation_snapshot().derive_node_to_tree()
- assert mapping["root"] == "root"
- assert mapping["root_status"] == "root"
- assert "child" not in mapping
- assert "child_status" not in mapping
+ replaced = store.load_conversation_snapshot().get_tree(_identity("root"))
+ assert replaced is not None
+ assert replaced.lookup_ids() == {"root", "root_status"}
- def test_remove_tree_removes_all_lookup_ids_for_that_root(self, tmp_path):
+ def test_remove_tree_removes_only_scoped_identity(self, tmp_path):
path = str(tmp_path / "sessions.json")
store = SessionStore(storage_path=path)
store.save_tree_snapshot(
TreeSnapshot(
+ scope=TELEGRAM_C1,
root_id="root",
nodes={
"root": _tree_node("root", "root_status"),
@@ -231,13 +357,9 @@ class TestSessionStoreTreeMappings:
)
)
- store.remove_tree_snapshot("root")
+ store.remove_tree_snapshot(_identity("root"))
- mapping = store.load_conversation_snapshot().derive_node_to_tree()
- assert "root" not in mapping
- assert "root_status" not in mapping
- assert "child" not in mapping
- assert "child_status" not in mapping
+ assert store.load_conversation_snapshot().get_tree(_identity("root")) is None
class TestSessionStoreAtomicWrites:
@@ -246,12 +368,16 @@ class TestSessionStoreAtomicWrites:
def test_failed_replace_keeps_prior_bytes_and_marks_dirty(self, tmp_path):
path = str(tmp_path / "sessions.json")
store = SessionStore(storage_path=path)
- store.save_tree_snapshot(TreeSnapshot(root_id="r1", nodes={"r1": {}}))
+ store.save_tree_snapshot(
+ TreeSnapshot(scope=TELEGRAM_C1, root_id="r1", nodes={"r1": {}})
+ )
store.flush_pending_save()
with open(path, encoding="utf-8") as f:
disk_after_first = f.read()
- store.save_tree_snapshot(TreeSnapshot(root_id="r2", nodes={"r2": {}}))
+ store.save_tree_snapshot(
+ TreeSnapshot(scope=TELEGRAM_C1, root_id="r2", nodes={"r2": {}})
+ )
with patch(
"free_claude_code.messaging.session.persistence.os.replace",
@@ -263,7 +389,7 @@ class TestSessionStoreAtomicWrites:
disk_after_failed = f.read()
assert disk_after_failed == disk_after_first
assert store.dirty is True
- assert store.get_tree_snapshot("r2") is not None
+ assert store.load_conversation_snapshot().get_tree(_identity("r2")) is not None
class TestSessionStoreClearAll:
@@ -273,6 +399,7 @@ class TestSessionStoreClearAll:
store.save_tree_snapshot(
TreeSnapshot(
+ scope=TELEGRAM_C1,
root_id="root1",
nodes={
"root1": {
@@ -304,7 +431,7 @@ class TestSessionStoreClearAll:
with open(path, encoding="utf-8") as f:
data = json.load(f)
- assert data["conversation"]["trees"] == {}
+ assert data["conversation"]["trees"] == []
assert data["message_log"] == {}
store2 = SessionStore(storage_path=path)
diff --git a/tests/messaging/test_telegram.py b/tests/messaging/test_telegram.py
index f5b4c73e..d00c6719 100644
--- a/tests/messaging/test_telegram.py
+++ b/tests/messaging/test_telegram.py
@@ -294,7 +294,6 @@ async def test_on_telegram_message_authorized(telegram_platform):
handler.assert_called_once()
incoming = handler.call_args[0][0]
assert incoming.text == "hello"
- assert incoming.user_id == "12345"
@pytest.mark.asyncio
diff --git a/tests/messaging/test_tree_concurrency.py b/tests/messaging/test_tree_concurrency.py
index 6e9b2d10..385223db 100644
--- a/tests/messaging/test_tree_concurrency.py
+++ b/tests/messaging/test_tree_concurrency.py
@@ -1,612 +1,308 @@
-"""Concurrency and race condition tests for tree data structures and queue manager."""
+"""Deterministic manager concurrency contracts."""
import asyncio
import pytest
-from free_claude_code.messaging.models import IncomingMessage
+from free_claude_code.messaging.models import IncomingMessage, MessageScope
from free_claude_code.messaging.trees import (
- MessageNode,
- MessageState,
- MessageTree,
+ CancellationReason,
+ CancellationUiOwner,
+ NodeClaim,
+ QueueEntry,
TreeQueueManager,
)
-from free_claude_code.messaging.trees.snapshot import (
- node_from_snapshot,
- node_to_snapshot,
-)
+
+_SCOPE = MessageScope(platform="telegram", chat_id="chat")
-def _make_incoming(text: str = "hello", msg_id: str = "m1") -> IncomingMessage:
- """Create a minimal IncomingMessage for testing."""
+def _incoming(node_id: str, *, reply_to: str | None = None) -> IncomingMessage:
return IncomingMessage(
- text=text,
- chat_id="chat1",
- user_id="user1",
- message_id=msg_id,
- platform="test",
+ text=f"prompt {node_id}",
+ chat_id=_SCOPE.chat_id,
+ user_id="user",
+ message_id=node_id,
+ platform=_SCOPE.platform,
+ reply_to_message_id=reply_to,
)
-def _make_tree(root_id: str = "root") -> MessageTree:
- """Create a tree with a single root node."""
- root = MessageNode(
- node_id=root_id,
- incoming=_make_incoming(msg_id=root_id),
- status_message_id=f"status_{root_id}",
- state=MessageState.PENDING,
- )
- return MessageTree(root)
-
-
-class TestMessageTreeConcurrency:
- """Concurrency tests for MessageTree operations."""
-
- @pytest.mark.asyncio
- async def test_concurrent_add_node_serialized(self):
- """Concurrent add_node calls should all succeed via lock serialization."""
- tree = _make_tree("root")
- count = 10
-
- async def add(i: int):
- return await tree.add_node(
- node_id=f"child_{i}",
- incoming=_make_incoming(msg_id=f"child_{i}"),
- status_message_id=f"status_{i}",
- parent_id="root",
- )
-
- results = await asyncio.gather(*[add(i) for i in range(count)])
-
- assert len(results) == count
- # All nodes plus root
- assert len(tree.all_nodes()) == count + 1
- # Root should have all children
- root = tree.get_root()
- assert len(root.children_ids) == count
-
- @pytest.mark.asyncio
- async def test_concurrent_enqueue_dequeue_no_loss(self):
- """Concurrent enqueue/dequeue should not lose items."""
- tree = _make_tree("root")
-
- # Add nodes first
- for i in range(10):
- await tree.add_node(
- node_id=f"n{i}",
- incoming=_make_incoming(msg_id=f"n{i}"),
- status_message_id=f"s{i}",
- parent_id="root",
- )
-
- # Enqueue all concurrently
- await asyncio.gather(*[tree.enqueue(f"n{i}") for i in range(10)])
- assert tree.get_queue_size() == 10
-
- # Dequeue all
- dequeued = []
- for _ in range(10):
- nid = await tree.dequeue()
- if nid:
- dequeued.append(nid)
-
- assert len(dequeued) == 10
- assert set(dequeued) == {f"n{i}" for i in range(10)}
- assert tree.get_queue_size() == 0
-
- @pytest.mark.asyncio
- async def test_dequeue_empty_returns_none(self):
- """Dequeue on empty queue returns None."""
- tree = _make_tree("root")
- result = await tree.dequeue()
- assert result is None
-
- @pytest.mark.asyncio
- async def test_concurrent_update_state(self):
- """Concurrent state updates should all apply (last writer wins)."""
- tree = _make_tree("root")
- for i in range(5):
- await tree.add_node(
- node_id=f"n{i}",
- incoming=_make_incoming(msg_id=f"n{i}"),
- status_message_id=f"s{i}",
- parent_id="root",
- )
-
- # Update all nodes concurrently
- await asyncio.gather(
- *[tree.update_state(f"n{i}", MessageState.IN_PROGRESS) for i in range(5)]
+async def _wait_for_no_tasks(manager: TreeQueueManager) -> None:
+ loop = asyncio.get_running_loop()
+ for _ in range(30):
+ if manager.task_count() == 0:
+ return
+ checkpoint = asyncio.Event()
+ loop.call_soon(checkpoint.set)
+ await checkpoint.wait()
+ assert manager.task_count() == 0
+
+
+async def test_one_tree_processes_fifo_with_transition_owned_queue_updates() -> None:
+ node_ids = ("root", "a", "b", "c")
+ releases = {node_id: asyncio.Event() for node_id in node_ids}
+ completions = {node_id: asyncio.Event() for node_id in node_ids}
+ started: asyncio.Queue[str] = asyncio.Queue()
+ started_callbacks: list[str] = []
+ queue_updates: list[tuple[tuple[str, int], ...]] = []
+ manager: TreeQueueManager
+
+ async def process(claim: NodeClaim) -> None:
+ node_id = claim.node.node_id
+ started.put_nowait(node_id)
+ await releases[node_id].wait()
+ await manager.complete_claim(claim, f"session-{node_id}")
+ completions[node_id].set()
+
+ async def capture_started(claim: NodeClaim) -> None:
+ started_callbacks.append(claim.node.node_id)
+
+ async def capture_queue(queue: tuple[QueueEntry, ...]) -> None:
+ queue_updates.append(
+ tuple((entry.node.node_id, entry.position) for entry in queue)
)
- for i in range(5):
- node = tree.get_node(f"n{i}")
- assert node is not None
- assert node.state == MessageState.IN_PROGRESS
-
- @pytest.mark.asyncio
- async def test_update_state_nonexistent_node(self):
- """Updating state of a nonexistent node should not raise."""
- tree = _make_tree("root")
- # Should just log a warning, not raise
- await tree.update_state("nonexistent", MessageState.ERROR)
-
- @pytest.mark.asyncio
- async def test_add_node_invalid_parent_raises(self):
- """Adding a node with nonexistent parent should raise ValueError."""
- tree = _make_tree("root")
- with pytest.raises(ValueError, match="not found in tree"):
- await tree.add_node(
- node_id="child",
- incoming=_make_incoming(),
- status_message_id="s1",
- parent_id="nonexistent",
- )
-
- @pytest.mark.asyncio
- async def test_queue_snapshot_matches_enqueue_order(self):
- """Queue snapshot should return items in FIFO order."""
- tree = _make_tree("root")
- for i in range(5):
- await tree.add_node(
- node_id=f"n{i}",
- incoming=_make_incoming(msg_id=f"n{i}"),
- status_message_id=f"s{i}",
- parent_id="root",
- )
-
- for i in range(5):
- await tree.enqueue(f"n{i}")
-
- snapshot = await tree.get_queue_snapshot()
- assert snapshot == [f"n{i}" for i in range(5)]
-
- @pytest.mark.asyncio
- async def test_enqueue_returns_position(self):
- """Enqueue should return 1-indexed position."""
- tree = _make_tree("root")
- for i in range(3):
- await tree.add_node(
- node_id=f"n{i}",
- incoming=_make_incoming(msg_id=f"n{i}"),
- status_message_id=f"s{i}",
- parent_id="root",
- )
-
- pos1 = await tree.enqueue("n0")
- pos2 = await tree.enqueue("n1")
- pos3 = await tree.enqueue("n2")
-
- assert pos1 == 1
- assert pos2 == 2
- assert pos3 == 3
-
-
-class TestMessageTreeNavigation:
- """Tests for tree navigation methods."""
-
- @pytest.mark.asyncio
- async def test_get_children(self):
- """get_children returns child nodes."""
- tree = _make_tree("root")
- await tree.add_node("c1", _make_incoming(msg_id="c1"), "s1", "root")
- await tree.add_node("c2", _make_incoming(msg_id="c2"), "s2", "root")
-
- children = tree.get_children("root")
- assert len(children) == 2
- assert {c.node_id for c in children} == {"c1", "c2"}
-
- def test_get_children_nonexistent(self):
- """get_children for nonexistent node returns empty list."""
- tree = _make_tree("root")
- assert tree.get_children("nonexistent") == []
-
- def test_get_parent_root(self):
- """Root node has no parent."""
- tree = _make_tree("root")
- assert tree.get_parent("root") is None
-
- @pytest.mark.asyncio
- async def test_get_parent_child(self):
- """Child node's parent is the root."""
- tree = _make_tree("root")
- await tree.add_node("c1", _make_incoming(msg_id="c1"), "s1", "root")
- parent = tree.get_parent("c1")
- assert parent is not None
- assert parent.node_id == "root"
-
- @pytest.mark.asyncio
- async def test_get_parent_session_id(self):
- """get_parent_session_id returns parent's session_id."""
- tree = _make_tree("root")
- await tree.update_state("root", MessageState.COMPLETED, session_id="sess_abc")
- await tree.add_node("c1", _make_incoming(msg_id="c1"), "s1", "root")
-
- session_id = tree.get_parent_session_id("c1")
- assert session_id == "sess_abc"
-
- def test_get_parent_session_id_root(self):
- """Root node has no parent session."""
- tree = _make_tree("root")
- assert tree.get_parent_session_id("root") is None
-
- def test_has_node(self):
- """has_node returns True for existing nodes."""
- tree = _make_tree("root")
- assert tree.has_node("root") is True
- assert tree.has_node("nonexistent") is False
-
- @pytest.mark.asyncio
- async def test_find_node_by_status_message(self):
- """find_node_by_status_message finds the right node."""
- tree = _make_tree("root")
- await tree.add_node("c1", _make_incoming(msg_id="c1"), "status_c1", "root")
-
- found = tree.find_node_by_status_message("status_c1")
- assert found is not None
- assert found.node_id == "c1"
-
- def test_find_node_by_status_message_not_found(self):
- """find_node_by_status_message returns None if not found."""
- tree = _make_tree("root")
- assert tree.find_node_by_status_message("nonexistent") is None
-
-
-class TestMessageTreeSerialization:
- """Tests for tree serialization/deserialization."""
-
- @pytest.mark.asyncio
- async def test_round_trip(self):
- """Tree should survive serialization round-trip."""
- tree = _make_tree("root")
- await tree.add_node("c1", _make_incoming(msg_id="c1"), "s1", "root")
- await tree.add_node("c2", _make_incoming(msg_id="c2"), "s2", "root")
- await tree.update_state("root", MessageState.COMPLETED, session_id="sess1")
-
- snapshot = tree.snapshot()
- restored = MessageTree.from_snapshot(snapshot)
-
- assert restored.root_id == "root"
- assert len(restored.all_nodes()) == 3
- root = restored.get_root()
- assert root.state == MessageState.COMPLETED
- assert root.session_id == "sess1"
- assert set(root.children_ids) == {"c1", "c2"}
-
- @pytest.mark.asyncio
- async def test_node_round_trip(self):
- """MessageNode should survive serialization round-trip."""
- node = MessageNode(
- node_id="n1",
- incoming=_make_incoming(msg_id="n1"),
- status_message_id="s1",
- state=MessageState.COMPLETED,
- parent_id="root",
- session_id="sess_test",
- error_message="test error",
- )
- data = node_to_snapshot(node)
- restored = node_from_snapshot(data)
-
- assert restored.node_id == "n1"
- assert restored.state == MessageState.COMPLETED
- assert restored.session_id == "sess_test"
- assert restored.error_message == "test error"
- assert restored.parent_id == "root"
-
-
-class TestTreeQueueManagerConcurrency:
- """Concurrency tests for TreeQueueManager."""
-
- @pytest.mark.asyncio
- async def test_concurrent_create_trees(self):
- """Creating multiple trees concurrently should all succeed."""
- mgr = TreeQueueManager()
-
- async def create(i: int):
- return await mgr.create_tree(
- node_id=f"root_{i}",
- incoming=_make_incoming(msg_id=f"root_{i}"),
- status_message_id=f"status_{i}",
- )
-
- trees = await asyncio.gather(*[create(i) for i in range(10)])
- assert len(trees) == 10
- assert mgr.get_tree_count() == 10
-
- @pytest.mark.asyncio
- async def test_add_to_tree_concurrent(self):
- """Adding replies to a tree concurrently should all succeed."""
- mgr = TreeQueueManager()
- await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
-
- async def add_reply(i: int):
- return await mgr.add_to_tree(
- parent_node_id="root",
- node_id=f"reply_{i}",
- incoming=_make_incoming(msg_id=f"reply_{i}"),
- status_message_id=f"s_reply_{i}",
- )
-
- results = await asyncio.gather(*[add_reply(i) for i in range(5)])
- assert len(results) == 5
- tree = mgr.get_tree("root")
- assert tree is not None
- assert len(tree.all_nodes()) == 6 # root + 5 replies
-
- @pytest.mark.asyncio
- async def test_add_to_tree_invalid_parent(self):
- """Adding to a nonexistent parent should raise ValueError."""
- mgr = TreeQueueManager()
- await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
-
- with pytest.raises(ValueError, match="not found"):
- await mgr.add_to_tree(
- parent_node_id="nonexistent",
- node_id="reply",
- incoming=_make_incoming(),
- status_message_id="s1",
- )
-
- @pytest.mark.asyncio
- async def test_enqueue_and_process(self):
- """Enqueue should process immediately if tree is free."""
- mgr = TreeQueueManager()
- await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
-
- processed = []
-
- async def processor(node_id, node):
- processed.append(node_id)
-
- queued = await mgr.enqueue("root", processor)
- # Should process immediately (not queued)
- assert queued is False
-
- # Wait for the async task to complete
- await asyncio.sleep(0.1)
- assert "root" in processed
-
- @pytest.mark.asyncio
- async def test_enqueue_queues_when_busy(self):
- """Enqueue should queue when tree is already processing."""
- mgr = TreeQueueManager()
- await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
- _, _ = await mgr.add_to_tree("root", "c1", _make_incoming(msg_id="c1"), "s1")
-
- processing_started = asyncio.Event()
- release = asyncio.Event()
-
- async def slow_processor(node_id, node):
- processing_started.set()
- await release.wait()
-
- # Start processing root (will block)
- queued_first = await mgr.enqueue("root", slow_processor)
- assert queued_first is False
- await processing_started.wait()
-
- # Now tree is busy, second enqueue should be queued
- queued_second = await mgr.enqueue("c1", slow_processor)
- assert queued_second is True
-
- # Release the blocker so things clean up
- release.set()
- await asyncio.sleep(0.2)
-
- @pytest.mark.asyncio
- async def test_cancel_tree(self):
- """cancel_tree should cancel in-progress and queued nodes."""
- mgr = TreeQueueManager()
- tree = await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
- _, _ = await mgr.add_to_tree("root", "c1", _make_incoming(msg_id="c1"), "s1")
- _, _ = await mgr.add_to_tree("root", "c2", _make_incoming(msg_id="c2"), "s2")
-
- processing_started = asyncio.Event()
-
- async def slow_processor(node_id, node):
- processing_started.set()
- await asyncio.sleep(10) # Long running
-
- # Start processing root
- await mgr.enqueue("root", slow_processor)
- await processing_started.wait()
-
- # Queue additional nodes
- await mgr.enqueue("c1", slow_processor)
- await mgr.enqueue("c2", slow_processor)
-
- # Cancel the tree
- cancelled = await mgr.cancel_tree("root")
- assert len(cancelled) >= 1 # At least the current + queued
-
- # Tree should no longer be processing
- assert tree.is_processing is False
-
- @pytest.mark.asyncio
- async def test_cancel_nonexistent_tree(self):
- """cancel_tree for nonexistent tree returns empty list."""
- mgr = TreeQueueManager()
- result = await mgr.cancel_tree("nonexistent")
- assert result == []
-
- @pytest.mark.asyncio
- async def test_cancel_all(self):
- """cancel_all cancels all trees."""
- mgr = TreeQueueManager()
- await mgr.create_tree("t1", _make_incoming(msg_id="t1"), "s1")
- await mgr.create_tree("t2", _make_incoming(msg_id="t2"), "s2")
-
- # Mark nodes as PENDING (they already are by default)
- cancelled = await mgr.cancel_all()
- # Nodes were PENDING but not in queue, so cleanup_stale logic applies
- # At minimum, it should not raise
- assert isinstance(cancelled, list)
-
- @pytest.mark.asyncio
- async def test_cleanup_stale_nodes(self):
- """cleanup_stale_nodes marks PENDING/IN_PROGRESS nodes as ERROR."""
- mgr = TreeQueueManager()
- tree = await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
- _, _ = await mgr.add_to_tree("root", "c1", _make_incoming(msg_id="c1"), "s1")
-
- # Root is PENDING, c1 is PENDING
- count = mgr.cleanup_stale_nodes()
- assert count == 2
-
- root = tree.get_node("root")
- assert root is not None
- assert root.state == MessageState.ERROR
- assert root.error_message is not None
- assert "restart" in root.error_message
-
- @pytest.mark.asyncio
- async def test_mark_node_error_with_propagation(self):
- """mark_node_error should propagate to pending children."""
- mgr = TreeQueueManager()
- tree = await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
- _, _ = await mgr.add_to_tree("root", "c1", _make_incoming(msg_id="c1"), "s1")
- _, _ = await mgr.add_to_tree("c1", "c2", _make_incoming(msg_id="c2"), "s2")
-
- affected = await mgr.mark_node_error("root", "something failed")
- # root + c1 + c2 should all be marked
- assert len(affected) >= 1
- root = tree.get_node("root")
- assert root is not None
- assert root.state == MessageState.ERROR
-
- @pytest.mark.asyncio
- async def test_mark_node_error_nonexistent(self):
- """mark_node_error for nonexistent node returns empty."""
- mgr = TreeQueueManager()
- result = await mgr.mark_node_error("nonexistent", "err")
- assert result == []
-
- @pytest.mark.asyncio
- async def test_get_tree_for_node(self):
- """get_tree_for_node returns the right tree."""
- mgr = TreeQueueManager()
- await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
- _, _ = await mgr.add_to_tree("root", "c1", _make_incoming(msg_id="c1"), "s1")
-
- tree = mgr.get_tree_for_node("c1")
- assert tree is not None
- assert tree.root_id == "root"
-
- def test_get_tree_for_node_nonexistent(self):
- """get_tree_for_node returns None for unknown nodes."""
- mgr = TreeQueueManager()
- assert mgr.get_tree_for_node("nonexistent") is None
-
- @pytest.mark.asyncio
- async def test_enqueue_no_tree(self):
- """Enqueue for a node not in any tree returns False."""
- mgr = TreeQueueManager()
-
- async def dummy(nid, node):
- pass
-
- result = await mgr.enqueue("nonexistent", dummy)
- assert result is False
-
- @pytest.mark.asyncio
- async def test_serialization_round_trip(self):
- """TreeQueueManager should survive serialization round-trip."""
- mgr = TreeQueueManager()
- await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
- _, _ = await mgr.add_to_tree("root", "c1", _make_incoming(msg_id="c1"), "s1")
-
- snapshot = mgr.snapshot()
- restored = TreeQueueManager.from_snapshot(snapshot)
-
- assert restored.get_tree_count() == 1
- assert restored.get_node("c1") is not None
-
- @pytest.mark.asyncio
- async def test_rapid_messages_all_queued(self):
- """Rapid sequential enqueues should all be queued without loss."""
- mgr = TreeQueueManager()
- tree = await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
-
- # Add 10 child nodes
- for i in range(10):
- await mgr.add_to_tree(
- "root", f"c{i}", _make_incoming(msg_id=f"c{i}"), f"s{i}"
- )
-
- blocker = asyncio.Event()
-
- async def blocking_processor(nid, node):
- await blocker.wait()
-
- # Start processing root (blocks)
- await mgr.enqueue("root", blocking_processor)
- await asyncio.sleep(0.05) # Let task start
-
- # Rapidly enqueue all children
- results = []
- for i in range(10):
- r = await mgr.enqueue(f"c{i}", blocking_processor)
- results.append(r)
-
- # All should be queued (True)
- assert all(r is True for r in results)
- assert tree.get_queue_size() == 10
-
- # Cleanup
- blocker.set()
- await asyncio.sleep(0.1)
-
- @pytest.mark.asyncio
- async def test_concurrent_trees_independent(self):
- """Processing in one tree shouldn't affect another."""
- mgr = TreeQueueManager()
- await mgr.create_tree("t1", _make_incoming(msg_id="t1"), "s1")
- await mgr.create_tree("t2", _make_incoming(msg_id="t2"), "s2")
-
- processed = []
-
- async def processor(nid, node):
- processed.append(nid)
-
- # Process both trees
- await mgr.enqueue("t1", processor)
- await mgr.enqueue("t2", processor)
- await asyncio.sleep(0.2)
-
- assert "t1" in processed
- assert "t2" in processed
-
- @pytest.mark.asyncio
- async def test_callbacks_invoked(self):
- """Queue update and node started callbacks should fire."""
- queue_updates = []
- node_starts = []
-
- async def on_queue_update(tree):
- queue_updates.append(tree.root_id)
-
- async def on_node_started(tree, node_id):
- node_starts.append(node_id)
-
- mgr = TreeQueueManager(
- queue_update_callback=on_queue_update,
- node_started_callback=on_node_started,
+ manager = TreeQueueManager(
+ process,
+ queue_update_callback=capture_queue,
+ node_started_callback=capture_started,
+ )
+ root = await manager.admit(_incoming("root"), "status-root")
+ assert root.claim is not None
+ identity = root.claim.identity
+ assert await started.get() == "root"
+
+ decisions = [
+ await manager.admit(
+ _incoming(node_id, reply_to="root"),
+ f"status-{node_id}",
+ parent_node_id="root",
)
- await mgr.create_tree("root", _make_incoming(msg_id="root"), "s_root")
- _, _ = await mgr.add_to_tree("root", "c1", _make_incoming(msg_id="c1"), "s1")
+ for node_id in node_ids[1:]
+ ]
+ assert [decision.position for decision in decisions] == [1, 2, 3]
+
+ observed = ["root"]
+ for node_id in node_ids:
+ releases[node_id].set()
+ await completions[node_id].wait()
+ if node_id != node_ids[-1]:
+ observed.append(await started.get())
+
+ await _wait_for_no_tasks(manager)
+
+ assert observed == list(node_ids)
+ assert started_callbacks == ["a", "b", "c"]
+ assert queue_updates == [
+ (("b", 1), ("c", 2)),
+ (("c", 1),),
+ (),
+ ]
+ snapshot = await manager.snapshot()
+ assert {
+ node_id: snapshot.trees[identity].nodes[node_id]["state"]
+ for node_id in node_ids
+ } == dict.fromkeys(node_ids, "completed")
+
+
+async def test_separate_trees_process_in_parallel() -> None:
+ started = {node_id: asyncio.Event() for node_id in ("one", "two")}
+ releases = {node_id: asyncio.Event() for node_id in ("one", "two")}
+ completed = {node_id: asyncio.Event() for node_id in ("one", "two")}
+ all_started = asyncio.Event()
+ active = 0
+ maximum_active = 0
+ manager: TreeQueueManager
+
+ async def process(claim: NodeClaim) -> None:
+ nonlocal active, maximum_active
+ node_id = claim.node.node_id
+ active += 1
+ maximum_active = max(maximum_active, active)
+ started[node_id].set()
+ if all(event.is_set() for event in started.values()):
+ all_started.set()
+ try:
+ await releases[node_id].wait()
+ await manager.complete_claim(claim, f"session-{node_id}")
+ finally:
+ active -= 1
+ completed[node_id].set()
+
+ manager = TreeQueueManager(process)
+ await asyncio.gather(
+ manager.admit(_incoming("one"), "status-one"),
+ manager.admit(_incoming("two"), "status-two"),
+ )
+ await all_started.wait()
+
+ assert maximum_active == 2
+ assert active == 2
+ assert manager.get_tree_count() == 2
+
+ releases["one"].set()
+ releases["two"].set()
+ await asyncio.gather(*(event.wait() for event in completed.values()))
+ await _wait_for_no_tasks(manager)
+
+
+async def test_cancel_all_cancels_active_and_queued_work_across_trees() -> None:
+ active_started = {node_id: asyncio.Event() for node_id in ("one", "two")}
+ processed: list[str] = []
+
+ async def process(claim: NodeClaim) -> None:
+ node_id = claim.node.node_id
+ processed.append(node_id)
+ if node_id in active_started:
+ active_started[node_id].set()
+ await asyncio.Event().wait()
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("one"), "status-one")
+ await manager.admit(_incoming("two"), "status-two")
+ await asyncio.gather(*(event.wait() for event in active_started.values()))
+ await manager.admit(
+ _incoming("one-child", reply_to="one"),
+ "status-one-child",
+ parent_node_id="one",
+ )
+ await manager.admit(
+ _incoming("two-child", reply_to="two"),
+ "status-two-child",
+ parent_node_id="two",
+ )
- blocker = asyncio.Event()
+ result = await manager.cancel_all(reason=CancellationReason.STOP)
+
+ owners = {effect.node.node_id: effect.ui_owner for effect in result.effects}
+ assert owners == {
+ "one": CancellationUiOwner.RUNNER,
+ "one-child": CancellationUiOwner.WORKFLOW,
+ "two": CancellationUiOwner.RUNNER,
+ "two-child": CancellationUiOwner.WORKFLOW,
+ }
+ assert len(result.snapshots) == 2
+ assert {
+ node["state"]
+ for snapshot in result.snapshots
+ for node in snapshot.nodes.values()
+ } == {"error"}
+ assert set(processed) == {"one", "two"}
+ assert manager.task_count() == 0
+
+
+async def test_branch_removal_atomically_unindexes_subtree_and_preserves_sibling() -> (
+ None
+):
+ root_started = asyncio.Event()
+ release_root = asyncio.Event()
+ sibling_started = asyncio.Event()
+ release_sibling = asyncio.Event()
+ unexpected: list[str] = []
+
+ async def process(claim: NodeClaim) -> None:
+ node_id = claim.node.node_id
+ if node_id == "root":
+ root_started.set()
+ await release_root.wait()
+ elif node_id == "sibling":
+ sibling_started.set()
+ await release_sibling.wait()
+ else:
+ unexpected.append(node_id)
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+ await root_started.wait()
+ await manager.admit(
+ _incoming("branch", reply_to="root"),
+ "status-branch",
+ parent_node_id="root",
+ )
+ await manager.admit(
+ _incoming("leaf", reply_to="branch"),
+ "status-leaf",
+ parent_node_id="branch",
+ )
+ await manager.admit(
+ _incoming("sibling", reply_to="root"),
+ "status-sibling",
+ parent_node_id="root",
+ )
+
+ result = await manager.remove_branch(
+ _SCOPE,
+ "status-branch",
+ reason=CancellationReason.STOP,
+ )
- async def slow_proc(nid, node):
- if nid == "root":
- blocker.set()
- await asyncio.sleep(0.1)
+ assert result.removed_tree_identity is None
+ assert result.message_ids == frozenset(
+ {"branch", "status-branch", "leaf", "status-leaf"}
+ )
+ assert {
+ effect.node.node_id: effect.ui_owner for effect in result.cancellation.effects
+ } == {
+ "branch": CancellationUiOwner.WORKFLOW,
+ "leaf": CancellationUiOwner.WORKFLOW,
+ }
+ assert len(result.cancellation.snapshots) == 1
+ assert set(result.cancellation.snapshots[0].nodes) == {"root", "sibling"}
+ assert await manager.resolve_node_id(_SCOPE, "branch") is None
+ assert await manager.resolve_node_id(_SCOPE, "status-leaf") is None
+ assert await manager.resolve_node_id(_SCOPE, "sibling") == "sibling"
+
+ release_root.set()
+ await asyncio.wait_for(sibling_started.wait(), timeout=1)
+ assert unexpected == []
+ release_sibling.set()
+ await _wait_for_no_tasks(manager)
+
+
+async def test_root_removal_atomically_cancels_and_unindexes_entire_tree() -> None:
+ root_started = asyncio.Event()
+ processed: list[str] = []
+
+ async def process(claim: NodeClaim) -> None:
+ processed.append(claim.node.node_id)
+ root_started.set()
+ await asyncio.Event().wait()
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+ await root_started.wait()
+ await manager.admit(
+ _incoming("child", reply_to="root"),
+ "status-child",
+ parent_node_id="root",
+ )
- # Process root then c1 should be dequeued
- await mgr.enqueue("root", slow_proc)
- await blocker.wait()
- await mgr.enqueue("c1", slow_proc)
- await asyncio.sleep(0.5)
+ result = await manager.remove_branch(
+ _SCOPE,
+ "status-root",
+ reason=CancellationReason.STOP,
+ )
- # c1 was dequeued from queue, so callbacks should have fired
- assert len(queue_updates) >= 1 or len(node_starts) >= 1
+ assert result.removed_tree_identity is not None
+ assert result.removed_tree_identity.scope == _SCOPE
+ assert result.removed_tree_identity.root_id == "root"
+ assert result.message_ids == frozenset(
+ {"root", "status-root", "child", "status-child"}
+ )
+ assert {
+ effect.node.node_id: effect.ui_owner for effect in result.cancellation.effects
+ } == {
+ "root": CancellationUiOwner.RUNNER,
+ "child": CancellationUiOwner.WORKFLOW,
+ }
+ assert result.cancellation.snapshots == ()
+ assert manager.get_tree_count() == 0
+ assert manager.task_count() == 0
+ assert await manager.resolve_node_id(_SCOPE, "root") is None
+ assert await manager.resolve_node_id(_SCOPE, "status-child") is None
+ assert processed == ["root"]
diff --git a/tests/messaging/test_tree_customer_regressions.py b/tests/messaging/test_tree_customer_regressions.py
new file mode 100644
index 00000000..c93cca87
--- /dev/null
+++ b/tests/messaging/test_tree_customer_regressions.py
@@ -0,0 +1,119 @@
+"""Customer-visible regressions at the tree manager ownership boundary."""
+
+import asyncio
+
+import pytest
+
+from free_claude_code.messaging.models import IncomingMessage, MessageScope
+from free_claude_code.messaging.trees import (
+ ConversationSnapshot,
+ MessageState,
+ NodeClaim,
+ TreeIdentity,
+ TreeQueueManager,
+)
+
+
+def _incoming(chat_id: str) -> IncomingMessage:
+ return IncomingMessage(
+ text=f"prompt from {chat_id}",
+ chat_id=chat_id,
+ user_id=f"user-{chat_id}",
+ message_id="42",
+ platform="telegram",
+ )
+
+
+async def _wait_for_no_tasks(manager: TreeQueueManager) -> None:
+ for _ in range(100):
+ if manager.task_count() == 0:
+ return
+ await asyncio.sleep(0)
+ raise AssertionError("messaging claims did not finish")
+
+
+def _snapshot_chat_ids(snapshot: ConversationSnapshot) -> set[str]:
+ return {tree.scope.chat_id for tree in snapshot.trees.values()}
+
+
+async def test_same_telegram_ids_in_different_chats_remain_independent_after_restore() -> (
+ None
+):
+ async def process(_claim: NodeClaim) -> None:
+ return
+
+ manager = TreeQueueManager(process)
+
+ first = await manager.admit(_incoming("chat-a"), "99")
+ second = await manager.admit(_incoming("chat-b"), "99")
+ await _wait_for_no_tasks(manager)
+
+ assert first.accepted is True
+ assert second.accepted is True
+ assert manager.get_tree_count() == 2
+
+ snapshot = await manager.snapshot()
+ assert len(snapshot.trees) == 2
+ assert _snapshot_chat_ids(snapshot) == {"chat-a", "chat-b"}
+ chat_a = MessageScope(platform="telegram", chat_id="chat-a")
+ chat_b = MessageScope(platform="telegram", chat_id="chat-b")
+ assert snapshot.get_tree(TreeIdentity(scope=chat_a, root_id="42")) is not None
+ assert snapshot.get_tree(TreeIdentity(scope=chat_b, root_id="42")) is not None
+
+ restored = TreeQueueManager.from_snapshot(snapshot, process)
+
+ assert restored.get_tree_count() == 2
+ assert _snapshot_chat_ids(await restored.snapshot()) == {"chat-a", "chat-b"}
+ assert await restored.get_message_ids_for_chat("telegram", "chat-a") == {
+ "42",
+ "99",
+ }
+ assert await restored.get_message_ids_for_chat("telegram", "chat-b") == {
+ "42",
+ "99",
+ }
+ assert await restored.get_node(chat_a, "42") is not None
+ assert await restored.get_node(chat_b, "42") is not None
+
+
+async def test_successful_completion_overrides_recoverable_failure_and_records_session() -> (
+ None
+):
+ started = asyncio.Event()
+ release = asyncio.Event()
+
+ async def process(_claim: NodeClaim) -> None:
+ started.set()
+ await release.wait()
+
+ manager = TreeQueueManager(process)
+ decision = await manager.admit(_incoming("chat"), "99")
+ assert decision.claim is not None
+ await started.wait()
+
+ try:
+ failure = await manager.fail_claim(
+ decision.claim,
+ propagate=True,
+ )
+ assert failure.snapshot is not None
+ failed_node = next(iter(failure.snapshot.nodes.values()))
+ assert failed_node["state"] == MessageState.ERROR.value
+
+ completed = await manager.complete_claim(decision.claim, "session-42")
+
+ assert completed is not None
+ completed_node = next(iter(completed.nodes.values()))
+ assert completed_node["state"] == MessageState.COMPLETED.value
+ assert completed_node["session_id"] == "session-42"
+
+ persisted = await manager.snapshot()
+ persisted_node = next(iter(persisted.trees.values())).nodes.values()
+ persisted_node = next(iter(persisted_node))
+ assert persisted_node["state"] == MessageState.COMPLETED.value
+ assert persisted_node["session_id"] == "session-42"
+ finally:
+ release.set()
+ await _wait_for_no_tasks(manager)
diff --git a/tests/messaging/test_tree_ownership_concurrency.py b/tests/messaging/test_tree_ownership_concurrency.py
new file mode 100644
index 00000000..b1073311
--- /dev/null
+++ b/tests/messaging/test_tree_ownership_concurrency.py
@@ -0,0 +1,608 @@
+import asyncio
+import contextlib
+
+import pytest
+
+from free_claude_code.messaging.models import IncomingMessage, MessageScope
+from free_claude_code.messaging.trees import manager as manager_module
+from free_claude_code.messaging.trees.manager import TreeQueueManager
+from free_claude_code.messaging.trees.transitions import (
+ CancellationReason,
+ CancellationUiOwner,
+ NodeClaim,
+)
+
+_SCOPE = MessageScope(platform="telegram", chat_id="chat")
+
+
+def _incoming(node_id: str, *, reply_to: str | None = None) -> IncomingMessage:
+ return IncomingMessage(
+ text=node_id,
+ chat_id=_SCOPE.chat_id,
+ user_id="user",
+ message_id=node_id,
+ platform=_SCOPE.platform,
+ reply_to_message_id=reply_to,
+ )
+
+
+async def _wait_for_no_tasks(manager: TreeQueueManager) -> None:
+ loop = asyncio.get_running_loop()
+ for _ in range(20):
+ if manager.task_count() == 0:
+ return
+ checkpoint = asyncio.Event()
+ loop.call_soon(checkpoint.set)
+ await checkpoint.wait()
+ assert manager.task_count() == 0
+
+
+async def test_cancelled_finisher_cannot_erase_or_overlap_a_new_claim() -> None:
+ root_started = asyncio.Event()
+ cancellation_seen = asyncio.Event()
+ release_cleanup = asyncio.Event()
+ child_started = asyncio.Event()
+ release_child = asyncio.Event()
+ active = 0
+ maximum_active = 0
+
+ async def process(claim: NodeClaim) -> None:
+ nonlocal active, maximum_active
+ active += 1
+ maximum_active = max(maximum_active, active)
+ try:
+ if claim.node.node_id == "root":
+ root_started.set()
+ try:
+ await asyncio.Event().wait()
+ except asyncio.CancelledError:
+ cancellation_seen.set()
+ await release_cleanup.wait()
+ raise
+ child_started.set()
+ await release_child.wait()
+ finally:
+ active -= 1
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+ await root_started.wait()
+
+ cancellation = asyncio.create_task(
+ manager.cancel_node(_SCOPE, "root", reason=CancellationReason.STOP)
+ )
+ await cancellation_seen.wait()
+ child = await manager.admit(
+ _incoming("child", reply_to="root"),
+ "status-child",
+ parent_node_id="root",
+ )
+
+ assert child.position == 1
+ assert not child_started.is_set()
+ assert maximum_active == 1
+
+ release_cleanup.set()
+ await cancellation
+ await asyncio.wait_for(child_started.wait(), timeout=1)
+ assert maximum_active == 1
+
+ release_child.set()
+
+
+async def test_cancelled_runner_exception_cannot_fail_or_skip_queued_claim() -> None:
+ root_started = asyncio.Event()
+ child_started = asyncio.Event()
+ release_child = asyncio.Event()
+ unexpected_failures = []
+
+ async def process(claim: NodeClaim) -> None:
+ if claim.node.node_id == "root":
+ root_started.set()
+ try:
+ await asyncio.Event().wait()
+ except asyncio.CancelledError:
+ raise RuntimeError("runner escaped after cancellation") from None
+ child_started.set()
+ await release_child.wait()
+
+ manager = TreeQueueManager(
+ process,
+ unexpected_failure_callback=unexpected_failures.append,
+ )
+ await manager.admit(_incoming("root"), "status-root")
+ await root_started.wait()
+ await manager.admit(
+ _incoming("child", reply_to="root"),
+ "status-child",
+ parent_node_id="root",
+ )
+
+ try:
+ await manager.cancel_node(_SCOPE, "root", reason=CancellationReason.STOP)
+ await asyncio.wait_for(child_started.wait(), timeout=1)
+
+ assert len(unexpected_failures) == 1
+ assert unexpected_failures[0].affected == ()
+ assert unexpected_failures[0].queue_update is None
+ assert unexpected_failures[0].snapshot is None
+ finally:
+ release_child.set()
+ await _wait_for_no_tasks(manager)
+
+
+ "operation",
+ ["global_stop", "global_clear", "branch_clear"],
+)
+async def test_terminal_operation_serializes_with_successor_task_publication(
+ monkeypatch: pytest.MonkeyPatch,
+ operation: str,
+) -> None:
+ root_started = asyncio.Event()
+ release_root = asyncio.Event()
+ successor_selected = asyncio.Event()
+ release_successor_publication = asyncio.Event()
+ child_started = asyncio.Event()
+ child_exited = asyncio.Event()
+ release_child = asyncio.Event()
+
+ async def process(claim: NodeClaim) -> None:
+ if claim.node.node_id == "root":
+ root_started.set()
+ await release_root.wait()
+ return
+ child_started.set()
+ try:
+ await release_child.wait()
+ finally:
+ child_exited.set()
+
+ manager = TreeQueueManager(process)
+ root = await manager.admit(_incoming("root"), "status-root")
+ assert root.claim is not None
+ await root_started.wait()
+ await manager.admit(
+ _incoming("child", reply_to="root"),
+ "status-child",
+ parent_node_id="root",
+ )
+ tree = manager._repository.get_tree(root.claim.identity)
+ assert tree is not None
+ original_finish = tree.finish_and_claim_next
+
+ async def pause_after_successor_selection(claim_id: str):
+ completion = await original_finish(claim_id)
+ if completion.next_claim is not None:
+ successor_selected.set()
+ await release_successor_publication.wait()
+ return completion
+
+ monkeypatch.setattr(
+ tree,
+ "finish_and_claim_next",
+ pause_after_successor_selection,
+ )
+ operation_task: asyncio.Task | None = None
+ try:
+ release_root.set()
+ await successor_selected.wait()
+ if operation == "global_stop":
+ operation_task = asyncio.create_task(
+ manager.cancel_all(reason=CancellationReason.STOP)
+ )
+ elif operation == "global_clear":
+ operation_task = asyncio.create_task(
+ manager.clear_all(reason=CancellationReason.STOP)
+ )
+ else:
+ operation_task = asyncio.create_task(
+ manager.remove_branch(
+ _SCOPE,
+ "root",
+ reason=CancellationReason.STOP,
+ )
+ )
+ for _ in range(5):
+ await asyncio.sleep(0)
+ if operation_task.done():
+ break
+
+ assert not operation_task.done()
+ finally:
+ release_successor_publication.set()
+ try:
+ if operation_task is not None:
+ await operation_task
+ finally:
+ release_child.set()
+ await _wait_for_no_tasks(manager)
+
+ assert manager.get_tree_count() == (1 if operation == "global_stop" else 0)
+ assert manager.task_count() == 0
+ if child_started.is_set():
+ assert child_exited.is_set()
+
+
+async def test_duplicate_admission_is_rejected_and_processed_once() -> None:
+ started = asyncio.Event()
+ release = asyncio.Event()
+ calls: list[str] = []
+
+ async def process(claim: NodeClaim) -> None:
+ calls.append(claim.node.node_id)
+ started.set()
+ await release.wait()
+
+ manager = TreeQueueManager(process)
+ first = await manager.admit(_incoming("root"), "status-root")
+ duplicate = await manager.admit(_incoming("root"), "status-duplicate")
+ await started.wait()
+
+ assert first.accepted is True
+ assert duplicate.accepted is False
+ assert calls == ["root"]
+ assert manager.task_count() == 1
+
+ release.set()
+
+
+async def test_node_and_status_references_are_published_together() -> None:
+ release = asyncio.Event()
+
+ async def process(_claim: NodeClaim) -> None:
+ await release.wait()
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+
+ assert await manager.resolve_node_id(_SCOPE, "root") == "root"
+ assert await manager.resolve_node_id(_SCOPE, "status-root") == "root"
+
+ release.set()
+
+
+async def test_callback_failure_does_not_block_the_next_claim() -> None:
+ release_root = asyncio.Event()
+ child_started = asyncio.Event()
+ release_child = asyncio.Event()
+
+ async def process(claim: NodeClaim) -> None:
+ if claim.node.node_id == "root":
+ await release_root.wait()
+ else:
+ child_started.set()
+ await release_child.wait()
+
+ async def broken_queue_callback(_queue) -> None:
+ raise RuntimeError("UI unavailable")
+
+ async def broken_started_callback(_claim) -> None:
+ raise RuntimeError("UI unavailable")
+
+ manager = TreeQueueManager(
+ process,
+ queue_update_callback=broken_queue_callback,
+ node_started_callback=broken_started_callback,
+ )
+ await manager.admit(_incoming("root"), "status-root")
+ await manager.admit(
+ _incoming("child", reply_to="root"),
+ "status-child",
+ parent_node_id="root",
+ )
+
+ release_root.set()
+ await asyncio.wait_for(child_started.wait(), timeout=1)
+ release_child.set()
+
+
+async def test_branch_removal_cannot_leave_a_detached_running_descendant() -> None:
+ root_started = asyncio.Event()
+ release_root = asyncio.Event()
+
+ async def process(claim: NodeClaim) -> None:
+ if claim.node.node_id == "root":
+ root_started.set()
+ await release_root.wait()
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+ await root_started.wait()
+ await manager.admit(
+ _incoming("branch", reply_to="root"),
+ "status-branch",
+ parent_node_id="root",
+ )
+
+ removed = await manager.remove_branch(_SCOPE, "branch")
+ late = await manager.admit(
+ _incoming("late", reply_to="branch"),
+ "status-late",
+ parent_node_id="branch",
+ )
+
+ assert removed.message_ids == frozenset({"branch", "status-branch"})
+ assert await manager.resolve_node_id(_SCOPE, "branch") is None
+ assert late.accepted is True
+ late_node = await manager.get_node(_SCOPE, "late")
+ assert late_node is not None
+ assert late_node.parent_id is None
+
+ release_root.set()
+
+
+async def test_clear_all_drains_terminal_claim_task_before_returning() -> None:
+ terminal = asyncio.Event()
+ release_cleanup = asyncio.Event()
+ cleanup_finished = asyncio.Event()
+ manager: TreeQueueManager
+
+ async def process(claim: NodeClaim) -> None:
+ await manager.complete_claim(claim, "session-root")
+ terminal.set()
+ try:
+ await release_cleanup.wait()
+ finally:
+ cleanup_finished.set()
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+ await terminal.wait()
+
+ try:
+ await manager.clear_all(reason=CancellationReason.STOP)
+
+ assert cleanup_finished.is_set()
+ assert manager.task_count() == 0
+ assert manager.get_tree_count() == 0
+ finally:
+ release_cleanup.set()
+ await _wait_for_no_tasks(manager)
+
+
+async def test_clear_all_returns_committed_result_after_caller_cancellation() -> None:
+ runner_cancelled = asyncio.Event()
+ release_cleanup = asyncio.Event()
+ cleanup_finished = asyncio.Event()
+
+ async def process(_claim: NodeClaim) -> None:
+ try:
+ await asyncio.Event().wait()
+ except asyncio.CancelledError:
+ runner_cancelled.set()
+ try:
+ await release_cleanup.wait()
+ finally:
+ cleanup_finished.set()
+ raise
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+ checkpoint = asyncio.Event()
+ asyncio.get_running_loop().call_soon(checkpoint.set)
+ await checkpoint.wait()
+
+ clear_task = asyncio.create_task(manager.clear_all(reason=CancellationReason.STOP))
+ await runner_cancelled.wait()
+
+ try:
+ clear_task.cancel()
+ cancellation_checkpoint = asyncio.Event()
+ asyncio.get_running_loop().call_soon(cancellation_checkpoint.set)
+ await cancellation_checkpoint.wait()
+
+ assert not clear_task.done()
+ release_cleanup.set()
+ result = await clear_task
+ assert {effect.node.node_id for effect in result.effects} == {"root"}
+ assert cleanup_finished.is_set()
+ assert manager.task_count() == 0
+ assert manager.get_tree_count() == 0
+ finally:
+ release_cleanup.set()
+ if not clear_task.done():
+ clear_task.cancel()
+ with contextlib.suppress(asyncio.CancelledError):
+ await clear_task
+ await _wait_for_no_tasks(manager)
+
+
+async def test_eager_task_factory_cannot_run_claim_before_admission_returns() -> None:
+ started = asyncio.Event()
+ release = asyncio.Event()
+
+ async def process(_claim: NodeClaim) -> None:
+ started.set()
+ await release.wait()
+
+ manager = TreeQueueManager(process)
+ loop = asyncio.get_running_loop()
+ original_factory = loop.get_task_factory()
+ try:
+ loop.set_task_factory(asyncio.eager_task_factory)
+ decision = await manager.admit(_incoming("root"), "status-root")
+ finally:
+ loop.set_task_factory(original_factory)
+
+ try:
+ assert decision.accepted is True
+ assert decision.claim is not None
+ assert decision.claim.node.scope == _SCOPE
+ assert manager.task_count() == 1
+ assert not started.is_set()
+ await asyncio.sleep(0)
+ assert started.is_set()
+ finally:
+ release.set()
+ await _wait_for_no_tasks(manager)
+
+
+async def test_absorbed_pre_run_cancellation_cannot_start_node_processor() -> None:
+ root_started = asyncio.Event()
+ release_root = asyncio.Event()
+ callback_entered = asyncio.Event()
+ callback_absorbed_cancellation = asyncio.Event()
+ child_processor_started = asyncio.Event()
+
+ async def process(claim: NodeClaim) -> None:
+ if claim.node.node_id == "root":
+ root_started.set()
+ await release_root.wait()
+ return
+ child_processor_started.set()
+
+ async def announce_started(claim: NodeClaim) -> None:
+ if claim.node.node_id != "child":
+ return
+ callback_entered.set()
+ try:
+ await asyncio.Event().wait()
+ except asyncio.CancelledError:
+ callback_absorbed_cancellation.set()
+
+ manager = TreeQueueManager(process, node_started_callback=announce_started)
+ await manager.admit(_incoming("root"), "status-root")
+ await root_started.wait()
+ child = await manager.admit(
+ _incoming("child", reply_to="root"),
+ "status-child",
+ parent_node_id="root",
+ )
+ assert child.position == 1
+
+ release_root.set()
+ await callback_entered.wait()
+ result = await manager.cancel_node(
+ _SCOPE,
+ "child",
+ reason=CancellationReason.STOP,
+ )
+
+ assert callback_absorbed_cancellation.is_set()
+ assert not child_processor_started.is_set()
+ assert [(effect.node.node_id, effect.ui_owner) for effect in result.effects] == [
+ ("child", CancellationUiOwner.WORKFLOW)
+ ]
+ node = await manager.get_node(_SCOPE, "child")
+ assert node is not None and node.state.value == "error"
+ await _wait_for_no_tasks(manager)
+
+
+async def test_same_scoped_root_can_be_readmitted_while_detached_claim_finishes(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(manager_module, "CANCEL_TASK_DRAIN_TIMEOUT_S", 0.01)
+ old_started = asyncio.Event()
+ old_cancelled = asyncio.Event()
+ release_old = asyncio.Event()
+ new_started = asyncio.Event()
+ release_new = asyncio.Event()
+ claims: list[NodeClaim] = []
+
+ async def process(claim: NodeClaim) -> None:
+ claims.append(claim)
+ if len(claims) == 1:
+ old_started.set()
+ while True:
+ try:
+ await release_old.wait()
+ return
+ except asyncio.CancelledError:
+ old_cancelled.set()
+ new_started.set()
+ await release_new.wait()
+
+ manager = TreeQueueManager(process)
+ old = await manager.admit(_incoming("root"), "status-root")
+ await old_started.wait()
+
+ try:
+ cleared = await manager.clear_all(reason=CancellationReason.STOP)
+ await old_cancelled.wait()
+ assert {effect.node.node_id for effect in cleared.effects} == {"root"}
+ assert manager.get_tree_count() == 0
+ assert manager.task_count() == 1
+
+ new = await manager.admit(_incoming("root"), "status-root")
+ await new_started.wait()
+
+ assert old.claim is not None
+ assert new.claim is not None
+ assert new.accepted is True
+ assert new.claim.identity == old.claim.identity
+ assert new.claim.claim_id != old.claim.claim_id
+ assert manager.task_count() == 2
+ finally:
+ release_old.set()
+ release_new.set()
+ await _wait_for_no_tasks(manager)
+
+
+async def test_active_error_claim_can_be_cancelled_again(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(manager_module, "CANCEL_TASK_DRAIN_TIMEOUT_S", 0.01)
+ started = asyncio.Event()
+ first_cancellation = asyncio.Event()
+ second_cancellation = asyncio.Event()
+ release = asyncio.Event()
+ cancellation_count = 0
+
+ async def process(_claim: NodeClaim) -> None:
+ nonlocal cancellation_count
+ started.set()
+ while True:
+ try:
+ await release.wait()
+ return
+ except asyncio.CancelledError:
+ cancellation_count += 1
+ if cancellation_count == 1:
+ first_cancellation.set()
+ continue
+ second_cancellation.set()
+ raise
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+ await started.wait()
+
+ try:
+ first = await manager.cancel_node(
+ _SCOPE,
+ "root",
+ reason=CancellationReason.STOP,
+ )
+ await first_cancellation.wait()
+ assert first.effects[0].ui_owner is CancellationUiOwner.RUNNER
+ assert manager.task_count() == 1
+
+ second = await manager.cancel_node(
+ _SCOPE,
+ "root",
+ reason=CancellationReason.STOP,
+ )
+ await second_cancellation.wait()
+
+ assert [
+ (effect.node.node_id, effect.ui_owner) for effect in second.effects
+ ] == [("root", CancellationUiOwner.RUNNER)]
+ assert cancellation_count == 2
+ await _wait_for_no_tasks(manager)
+ finally:
+ release.set()
+ await _wait_for_no_tasks(manager)
diff --git a/tests/messaging/test_tree_processor.py b/tests/messaging/test_tree_processor.py
index d2433e07..510a891e 100644
--- a/tests/messaging/test_tree_processor.py
+++ b/tests/messaging/test_tree_processor.py
@@ -1,262 +1,202 @@
+"""Manager-level task and cancellation ownership tests."""
+
import asyncio
-import contextlib
-from unittest.mock import AsyncMock, MagicMock
import pytest
-from free_claude_code.messaging.models import IncomingMessage
-from free_claude_code.messaging.trees import MessageNode, MessageState, MessageTree
-from free_claude_code.messaging.trees.processor import TreeQueueProcessor
-
+from free_claude_code.messaging.models import IncomingMessage, MessageScope
+from free_claude_code.messaging.trees import (
+ CancellationReason,
+ CancellationUiOwner,
+ FailureResult,
+ MessageState,
+ NodeClaim,
+ QueueEntry,
+ TreeQueueManager,
+)
+from free_claude_code.messaging.trees import manager as manager_module
-def tree_processor():
- return TreeQueueProcessor()
+_SCOPE = MessageScope(platform="telegram", chat_id="chat")
-def sample_incoming():
+def _incoming(node_id: str, *, reply_to: str | None = None) -> IncomingMessage:
return IncomingMessage(
- text="test message",
- chat_id="chat123",
- user_id="user456",
- message_id="msg789",
- platform="telegram",
- )
-
-
-def sample_node(sample_incoming):
- return MessageNode(
- node_id="msg789", incoming=sample_incoming, status_message_id="status123"
+ text=f"prompt {node_id}",
+ chat_id=_SCOPE.chat_id,
+ user_id="user",
+ message_id=node_id,
+ platform=_SCOPE.platform,
+ reply_to_message_id=reply_to,
)
-def sample_tree(sample_node):
- return MessageTree(sample_node)
+async def _wait_for_no_tasks(manager: TreeQueueManager) -> None:
+ """Yield deterministic ready-queue checkpoints until task cleanup completes."""
+ loop = asyncio.get_running_loop()
+ for _ in range(20):
+ if manager.task_count() == 0:
+ return
+ checkpoint = asyncio.Event()
+ loop.call_soon(checkpoint.set)
+ await checkpoint.wait()
+ assert manager.task_count() == 0
@pytest.mark.asyncio
-async def test_process_node_success(tree_processor, sample_tree, sample_node):
- processor = AsyncMock()
-
- await tree_processor.process_node(sample_tree, sample_node, processor)
-
- processor.assert_called_once_with(sample_node.node_id, sample_node)
- assert sample_tree.current_node_id is None
-
-
-async def test_process_node_cancelled(tree_processor, sample_tree, sample_node):
- processor = AsyncMock(side_effect=asyncio.CancelledError)
-
- with pytest.raises(asyncio.CancelledError):
- await tree_processor.process_node(sample_tree, sample_node, processor)
-
- assert sample_tree.current_node_id is None
-
-
-async def test_process_node_exception(tree_processor, sample_tree, sample_node):
- processor = AsyncMock(side_effect=Exception("Test error"))
-
- # We need to mock update_state to verify it was called
- sample_tree.update_state = AsyncMock()
-
- await tree_processor.process_node(sample_tree, sample_node, processor)
-
- sample_tree.update_state.assert_called_once_with(
- sample_node.node_id, MessageState.ERROR, error_message="Test error"
+async def test_active_cancel_returns_runner_owned_effect_and_terminal_snapshot() -> (
+ None
+):
+ started = asyncio.Event()
+
+ async def process(_claim: NodeClaim) -> None:
+ started.set()
+ await asyncio.Event().wait()
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+ await started.wait()
+
+ result = await manager.cancel_node(
+ _SCOPE,
+ "root",
+ reason=CancellationReason.STOP,
)
- assert sample_tree.current_node_id is None
-
-
-async def test_enqueue_and_start_when_free(tree_processor, sample_tree):
- processor = AsyncMock()
- node_id = "node1"
-
- # Mock get_node to return a node
- node = MagicMock(spec=MessageNode)
- sample_tree.get_node = MagicMock(return_value=node)
- was_queued = await tree_processor.enqueue_and_start(sample_tree, node_id, processor)
-
- assert was_queued is False
- assert sample_tree.is_processing is True
- assert sample_tree.current_node_id == node_id
- assert sample_tree.current_task is not None
-
- # Clean up task
- sample_tree.current_task.cancel()
- with contextlib.suppress(asyncio.CancelledError):
- await sample_tree.current_task
+ assert [(effect.node.node_id, effect.ui_owner) for effect in result.effects] == [
+ ("root", CancellationUiOwner.RUNNER)
+ ]
+ assert len(result.snapshots) == 1
+ assert result.snapshots[0].nodes["root"]["state"] == "error"
+ view = await manager.get_node(_SCOPE, "root")
+ assert view is not None and view.state is MessageState.ERROR
+ assert manager.task_count() == 0
@pytest.mark.asyncio
-async def test_enqueue_and_start_when_busy(tree_processor, sample_tree):
- processor = AsyncMock()
- sample_tree.set_processing_state("busy", True)
- node_id = "node1"
-
- was_queued = await tree_processor.enqueue_and_start(sample_tree, node_id, processor)
-
- assert was_queued is True
- assert sample_tree._queue.qsize() == 1
- assert sample_tree._queue.get_nowait() == node_id
-
-
-def test_cancel_current_task(tree_processor, sample_tree):
- mock_task = MagicMock(spec=asyncio.Task)
- mock_task.done.return_value = False
- sample_tree.set_current_task(mock_task)
-
- cancelled = tree_processor.cancel_current(sample_tree)
-
- assert cancelled is mock_task
- mock_task.cancel.assert_called_once()
-
-
-def test_cancel_current_task_already_done(tree_processor, sample_tree):
- mock_task = MagicMock(spec=asyncio.Task)
- mock_task.done.return_value = True
- sample_tree.set_current_task(mock_task)
-
- cancelled = tree_processor.cancel_current(sample_tree)
-
- assert cancelled is None
- mock_task.cancel.assert_not_called()
-
-
-async def test_process_next_queue_empty(tree_processor, sample_tree):
- processor = AsyncMock()
- sample_tree.set_processing_state("busy", True)
-
- await tree_processor._process_next(sample_tree, processor)
-
- assert sample_tree.is_processing is False
-
-
-async def test_process_next_with_item(tree_processor, sample_tree):
- processor = AsyncMock()
- sample_tree.put_queue_unlocked("next_node")
-
- node = MagicMock(spec=MessageNode)
- sample_tree.get_node = MagicMock(return_value=node)
-
- await tree_processor._process_next(sample_tree, processor)
-
- assert sample_tree.current_node_id == "next_node"
- assert sample_tree.current_task is not None
-
- # Clean up
- sample_tree.current_task.cancel()
- with contextlib.suppress(asyncio.CancelledError):
- 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,
+async def test_queued_cancel_returns_workflow_effect_and_exact_queue_update() -> None:
+ release_root = asyncio.Event()
+ root_started = asyncio.Event()
+ child_started = asyncio.Event()
+ queue_updates: list[tuple[tuple[str, int], ...]] = []
+
+ async def process(claim: NodeClaim) -> None:
+ if claim.node.node_id == "root":
+ root_started.set()
+ await release_root.wait()
+ else:
+ child_started.set()
+
+ async def capture_queue(queue: tuple[QueueEntry, ...]) -> None:
+ queue_updates.append(
+ tuple((entry.node.node_id, entry.position) for entry in queue)
+ )
+
+ manager = TreeQueueManager(process, queue_update_callback=capture_queue)
+ await manager.admit(_incoming("root"), "status-root")
+ await root_started.wait()
+ decision = await manager.admit(
+ _incoming("child", reply_to="root"),
+ "status-child",
+ parent_node_id="root",
)
- release = asyncio.Event()
+ assert decision.position == 1
- 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,
+ result = await manager.cancel_node(
+ _SCOPE,
+ "child",
+ reason=CancellationReason.STOP,
)
- sample_tree.put_queue_unlocked("missing_node")
- sample_tree.put_queue_unlocked("valid_node")
- async def node_processor(node_id, node):
- await release.wait()
+ assert [(effect.node.node_id, effect.ui_owner) for effect in result.effects] == [
+ ("child", CancellationUiOwner.WORKFLOW)
+ ]
+ assert queue_updates == [()]
+ assert result.snapshots[0].nodes["child"]["state"] == "error"
+ assert child_started.is_set() is False
- 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.set_processing_state("busy", True)
- sample_tree.put_queue_unlocked("missing_one")
- sample_tree.put_queue_unlocked("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)
+ release_root.set()
+ await _wait_for_no_tasks(manager)
+ assert child_started.is_set() is False
@pytest.mark.asyncio
-async def test_process_next_triggers_queue_update(sample_tree):
- callback = AsyncMock()
- processor = TreeQueueProcessor(queue_update_callback=callback)
-
- sample_tree.put_queue_unlocked("next_node")
- sample_tree.get_node = MagicMock(return_value=None)
-
- await processor._process_next(sample_tree, AsyncMock())
-
- callback.assert_awaited_once_with(sample_tree)
+async def test_cancel_cleanup_timeout_is_bounded_and_task_remains_owned(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(manager_module, "CANCEL_TASK_DRAIN_TIMEOUT_S", 0.01)
+ started = asyncio.Event()
+ cancellation_seen = asyncio.Event()
+ release_cleanup = asyncio.Event()
+
+ async def process(_claim: NodeClaim) -> None:
+ started.set()
+ try:
+ await asyncio.Event().wait()
+ except asyncio.CancelledError:
+ cancellation_seen.set()
+ await release_cleanup.wait()
+ raise
+
+ manager = TreeQueueManager(process)
+ await manager.admit(_incoming("root"), "status-root")
+ await started.wait()
+
+ try:
+ result = await asyncio.wait_for(
+ manager.cancel_node(
+ _SCOPE,
+ "root",
+ reason=CancellationReason.STOP,
+ ),
+ timeout=0.5,
+ )
+ await cancellation_seen.wait()
+ assert result.effects[0].node.node_id == "root"
+ assert manager.task_count() == 1
+ finally:
+ release_cleanup.set()
+
+ await _wait_for_no_tasks(manager)
@pytest.mark.asyncio
-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,
+async def test_escaped_processor_failure_persists_effects_through_manager_owner() -> (
+ None
+):
+ started = asyncio.Event()
+ release = asyncio.Event()
+ failures: list[FailureResult] = []
+ queue_updates: list[tuple[QueueEntry, ...]] = []
+
+ async def process(claim: NodeClaim) -> None:
+ if claim.node.node_id == "root":
+ started.set()
+ await release.wait()
+ raise RuntimeError("processor boundary failed")
+
+ async def capture_queue(queue: tuple[QueueEntry, ...]) -> None:
+ queue_updates.append(queue)
+
+ manager = TreeQueueManager(
+ process,
+ queue_update_callback=capture_queue,
+ unexpected_failure_callback=failures.append,
)
- await sample_tree.add_node(
- "next_node", incoming, "next_status", sample_tree.root_id
+ await manager.admit(_incoming("root"), "status-root")
+ await started.wait()
+ await manager.admit(
+ _incoming("child", reply_to="root"),
+ "status-child",
+ parent_node_id="root",
)
- sample_tree.put_queue_unlocked("next_node")
-
- 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
+ release.set()
+ await _wait_for_no_tasks(manager)
+
+ assert len(failures) == 1
+ failure = failures[0]
+ assert failure.snapshot is not None
+ assert {target.node_id for target in failure.affected} == {"root", "child"}
+ assert failure.snapshot.nodes["root"]["state"] == "error"
+ assert failure.snapshot.nodes["child"]["state"] == "error"
+ assert queue_updates == [()]
diff --git a/tests/messaging/test_tree_queue.py b/tests/messaging/test_tree_queue.py
index 19bf7acd..8bfb4a2d 100644
--- a/tests/messaging/test_tree_queue.py
+++ b/tests/messaging/test_tree_queue.py
@@ -1,1073 +1,145 @@
-"""Tests for tree-based message queue system."""
-
-import asyncio
-import contextlib
-from unittest.mock import AsyncMock
+"""Focused tests for the tree package's private graph and queue values."""
import pytest
-from free_claude_code.messaging.models import IncomingMessage
-from free_claude_code.messaging.trees import (
- CancellationReason,
- CancellationUiOwner,
- MessageNode,
- MessageState,
- MessageTree,
- TreeQueueManager,
- TreeSnapshot,
- get_cancel_reason,
- set_cancel_reason,
-)
-from free_claude_code.messaging.trees import manager as tree_manager_module
+from free_claude_code.messaging.models import MessageScope
from free_claude_code.messaging.trees.graph import MessageTreeGraph
+from free_claude_code.messaging.trees.node import MessageNode, MessageState
+from free_claude_code.messaging.trees.queue import MessageNodeQueue
from free_claude_code.messaging.trees.snapshot import (
+ TreeSnapshot,
node_from_snapshot,
node_to_snapshot,
)
-
-class TestMessageState:
- """Test MessageState enum."""
-
- def test_state_values(self):
- """Test state enum values."""
- assert MessageState.PENDING.value == "pending"
- assert MessageState.IN_PROGRESS.value == "in_progress"
- assert MessageState.COMPLETED.value == "completed"
- assert MessageState.ERROR.value == "error"
-
-
-class TestMessageNode:
- """Test MessageNode dataclass."""
-
- def test_node_creation(self):
- """Test creating a message node."""
- incoming = IncomingMessage(
- text="Hello",
- chat_id="123",
- user_id="456",
- message_id="789",
- platform="telegram",
- )
- node = MessageNode(
- node_id="789",
- incoming=incoming,
- status_message_id="status_1",
- )
-
- assert node.node_id == "789"
- assert node.state == MessageState.PENDING
- assert node.parent_id is None
- assert node.children_ids == []
- assert node.session_id is None
-
- def test_node_to_snapshot(self):
- """Test serializing a node."""
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="2",
- message_id="3",
- platform="test",
- )
- node = MessageNode(
- node_id="3",
- incoming=incoming,
- status_message_id="s1",
- state=MessageState.COMPLETED,
- session_id="sess_123",
- )
-
- data = node_to_snapshot(node)
- assert data["node_id"] == "3"
- assert data["state"] == "completed"
- assert data["session_id"] == "sess_123"
-
- def test_node_from_snapshot(self):
- """Test deserializing a node."""
- data = {
- "node_id": "n1",
- "incoming": {
- "text": "Hello",
- "chat_id": "c1",
- "user_id": "u1",
- "message_id": "m1",
- "platform": "test",
- },
- "status_message_id": "s1",
- "state": "in_progress",
- "parent_id": "parent_1",
- "session_id": None,
- "children_ids": ["child_1"],
- "created_at": "2025-01-01T00:00:00",
- }
-
- node = node_from_snapshot(data)
- assert node.node_id == "n1"
- assert node.state == MessageState.IN_PROGRESS
- assert node.parent_id == "parent_1"
- assert "child_1" in node.children_ids
-
- def test_completed_state_clears_stale_error_message(self):
- """Successful completion is terminal and should clear prior node errors."""
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="2",
- message_id="3",
- platform="test",
- )
- node = MessageNode(node_id="3", incoming=incoming, status_message_id="s1")
- node.mark_error("temporary failure")
-
- node.update_state(MessageState.COMPLETED, session_id="session_1")
-
- assert node.state is MessageState.COMPLETED
- assert node.session_id == "session_1"
- assert node.error_message is None
-
- def test_cancel_reason_helpers_preserve_existing_context(self):
- """Cancellation reason is typed and does not clobber other context."""
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="2",
- message_id="3",
- platform="test",
- )
- node = MessageNode(node_id="3", incoming=incoming, status_message_id="s1")
- node.set_context({"other": "value"})
-
- set_cancel_reason(node, CancellationReason.STOP)
-
- assert get_cancel_reason(node) is CancellationReason.STOP
- assert node.context == {"other": "value", "cancel_reason": "stop"}
-
- set_cancel_reason(node, None)
-
- assert get_cancel_reason(node) is None
- assert node.context == {"other": "value"}
-
-
-class TestMessageTree:
- """Test MessageTree class."""
-
- def test_tree_creation(self):
- """Test creating a tree with root node."""
- incoming = IncomingMessage(
- text="Root",
- chat_id="1",
- user_id="1",
- message_id="root_msg",
- platform="test",
- )
- root = MessageNode(
- node_id="root_msg",
- incoming=incoming,
- status_message_id="status_1",
- )
-
- tree = MessageTree(root)
- assert tree.root_id == "root_msg"
- assert tree.get_node("root_msg") is not None
- assert tree.is_processing is False
-
- @pytest.mark.asyncio
- async def test_add_child_node(self):
- """Test adding a child node to the tree."""
- # Create root
- root_incoming = IncomingMessage(
- text="Root",
- chat_id="1",
- user_id="1",
- message_id="root",
- platform="test",
- )
- root = MessageNode(
- node_id="root",
- incoming=root_incoming,
- status_message_id="s1",
- )
- tree = MessageTree(root)
-
- # Add child
- child_incoming = IncomingMessage(
- text="Child",
- chat_id="1",
- user_id="1",
- message_id="child",
- platform="test",
- reply_to_message_id="root",
- )
- child = await tree.add_node(
- node_id="child",
- incoming=child_incoming,
- status_message_id="s2",
- parent_id="root",
- )
-
- assert child.node_id == "child"
- assert child.parent_id == "root"
- assert "child" in tree.get_root().children_ids
- parent = tree.get_parent("child")
- assert parent is not None
- assert parent.node_id == "root"
-
- @pytest.mark.asyncio
- async def test_update_state(self):
- """Test updating node state."""
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="1",
- message_id="m1",
- platform="test",
- )
- root = MessageNode(node_id="m1", incoming=incoming, status_message_id="s1")
- tree = MessageTree(root)
-
- await tree.update_state("m1", MessageState.IN_PROGRESS)
- node = tree.get_node("m1")
- assert node is not None
- assert node.state == MessageState.IN_PROGRESS
-
- await tree.update_state("m1", MessageState.COMPLETED, session_id="sess_abc")
- node = tree.get_node("m1")
- assert node is not None
- assert node.state == MessageState.COMPLETED
- assert node.session_id == "sess_abc"
- assert node.completed_at is not None
-
- @pytest.mark.asyncio
- async def test_enqueue_dequeue(self):
- """Test queue operations."""
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="1",
- message_id="m1",
- platform="test",
- )
- root = MessageNode(node_id="m1", incoming=incoming, status_message_id="s1")
- tree = MessageTree(root)
-
- # Enqueue
- pos = await tree.enqueue("m1")
- assert pos == 1
- assert tree.get_queue_size() == 1
-
- # Dequeue
- node_id = await tree.dequeue()
- assert node_id == "m1"
- assert tree.get_queue_size() == 0
-
- @pytest.mark.asyncio
- async def test_queue_snapshot(self):
- """Test queue snapshot order."""
- incoming = IncomingMessage(
- text="Root",
- chat_id="1",
- user_id="1",
- message_id="root",
- platform="test",
- )
- root = MessageNode(node_id="root", incoming=incoming, status_message_id="s1")
- tree = MessageTree(root)
-
- child_incoming_1 = IncomingMessage(
- text="Child 1",
- chat_id="1",
- user_id="1",
- message_id="child_1",
- platform="test",
- reply_to_message_id="root",
- )
- child_incoming_2 = IncomingMessage(
- text="Child 2",
- chat_id="1",
- user_id="1",
- message_id="child_2",
- platform="test",
- reply_to_message_id="root",
- )
-
- await tree.add_node(
- node_id="child_1",
- incoming=child_incoming_1,
- status_message_id="s2",
- parent_id="root",
- )
- await tree.add_node(
- node_id="child_2",
- incoming=child_incoming_2,
- status_message_id="s3",
- parent_id="root",
- )
-
- await tree.enqueue("child_1")
- await tree.enqueue("child_2")
-
- snapshot = await tree.get_queue_snapshot()
- assert snapshot == ["child_1", "child_2"]
-
- def test_tree_snapshot_round_trip(self):
- """Test tree snapshot round-trip."""
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="1",
- message_id="m1",
- platform="test",
- )
- root = MessageNode(
- node_id="m1",
- incoming=incoming,
- status_message_id="s1",
- state=MessageState.COMPLETED,
- session_id="sess_1",
- )
- tree = MessageTree(root)
-
- snapshot = tree.snapshot()
- restored = MessageTree.from_snapshot(snapshot)
-
- assert restored.root_id == "m1"
- node = restored.get_node("m1")
- assert node is not None
- assert node.session_id == "sess_1"
-
- def test_tree_from_snapshot_uses_one_graph_construction(self, monkeypatch):
- """Restore should not build a temporary graph and replace it."""
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="1",
- message_id="m1",
- platform="test",
- )
- root = MessageNode(
- node_id="m1",
- incoming=incoming,
- status_message_id="s1",
- )
- snapshot = MessageTree(root).snapshot()
- original_init = MessageTreeGraph.__init__
- init_calls = 0
-
- def counting_init(self: MessageTreeGraph, root_node: MessageNode) -> None:
- nonlocal init_calls
- init_calls += 1
- original_init(self, root_node)
-
- monkeypatch.setattr(MessageTreeGraph, "__init__", counting_init)
-
- restored = MessageTree.from_snapshot(snapshot)
-
- assert restored.root_id == "m1"
- assert init_calls == 1
-
- @pytest.mark.asyncio
- async def test_get_descendants(self):
- """Test get_descendants returns node and all descendants."""
- root_incoming = IncomingMessage(
- text="Root", chat_id="1", user_id="1", message_id="root", platform="test"
- )
- root = MessageNode(
- node_id="root", incoming=root_incoming, status_message_id="s1"
- )
- tree = MessageTree(root)
-
- child_incoming = IncomingMessage(
- text="Child",
- chat_id="1",
- user_id="1",
- message_id="child",
- platform="test",
- reply_to_message_id="root",
- )
- await tree.add_node("child", child_incoming, "s2", "root")
-
- grandchild_incoming = IncomingMessage(
- text="Grand",
- chat_id="1",
- user_id="1",
- message_id="grand",
- platform="test",
- reply_to_message_id="child",
- )
- await tree.add_node("grand", grandchild_incoming, "s3", "child")
-
- assert tree.get_descendants("root") == ["root", "child", "grand"]
- assert tree.get_descendants("child") == ["child", "grand"]
- assert tree.get_descendants("grand") == ["grand"]
- assert tree.get_descendants("nonexistent") == []
-
- @pytest.mark.asyncio
- async def test_remove_branch(self):
- """Test remove_branch removes subtree and updates parent."""
- root_incoming = IncomingMessage(
- text="Root", chat_id="1", user_id="1", message_id="root", platform="test"
- )
- root = MessageNode(
- node_id="root", incoming=root_incoming, status_message_id="s1"
- )
- tree = MessageTree(root)
-
- child_incoming = IncomingMessage(
- text="Child",
- chat_id="1",
- user_id="1",
- message_id="child",
- platform="test",
- reply_to_message_id="root",
- )
- await tree.add_node("child", child_incoming, "s2", "root")
-
- grandchild_incoming = IncomingMessage(
- text="Grand",
- chat_id="1",
- user_id="1",
- message_id="grand",
- platform="test",
- reply_to_message_id="child",
- )
- await tree.add_node("grand", grandchild_incoming, "s3", "child")
-
- async with tree.with_lock():
- removed = tree.remove_branch("child")
-
- assert len(removed) == 2
- assert {n.node_id for n in removed} == {"child", "grand"}
- assert tree.get_node("child") is None
- assert tree.get_node("grand") is None
- assert tree.get_node("root") is not None
- assert "child" not in tree.get_root().children_ids
-
-
-class TestTreeQueueManager:
- """Test TreeQueueManager class."""
-
- @pytest.mark.asyncio
- async def test_create_tree(self):
- """Test creating a new tree."""
- manager = TreeQueueManager()
-
- incoming = IncomingMessage(
- text="New message",
- chat_id="1",
- user_id="1",
- message_id="msg_1",
- platform="test",
- )
-
- tree = await manager.create_tree(
- node_id="msg_1",
- incoming=incoming,
- status_message_id="status_1",
- )
-
- assert tree is not None
- assert tree.root_id == "msg_1"
- assert manager.get_tree("msg_1") is tree
-
- @pytest.mark.asyncio
- async def test_add_reply_to_tree(self):
- """Test adding a reply to existing tree."""
- manager = TreeQueueManager()
-
- # Create root
- root_incoming = IncomingMessage(
- text="Root",
- chat_id="1",
- user_id="1",
- message_id="root",
- platform="test",
- )
- await manager.create_tree("root", root_incoming, "s1")
-
- # Add reply
- reply_incoming = IncomingMessage(
- text="Reply",
- chat_id="1",
- user_id="1",
- message_id="reply",
- platform="test",
- reply_to_message_id="root",
- )
- tree, node = await manager.add_to_tree(
- parent_node_id="root",
- node_id="reply",
- incoming=reply_incoming,
- status_message_id="s2",
- )
-
- assert node.parent_id == "root"
- assert manager.get_tree_for_node("reply") is tree
-
- @pytest.mark.asyncio
- async def test_enqueue_and_process(self):
- """Test enqueueing and processing."""
- manager = TreeQueueManager()
- processed = []
-
- async def processor(node_id, node):
- processed.append(node_id)
- await asyncio.sleep(0.01) # Simulate work
-
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="1",
- message_id="m1",
- platform="test",
- )
- await manager.create_tree("m1", incoming, "s1")
-
- was_queued = await manager.enqueue("m1", processor)
- assert was_queued is False # First message processes immediately
-
- # Wait for processing
- await asyncio.sleep(0.1)
- assert "m1" in processed
-
- @pytest.mark.asyncio
- async def test_queue_when_busy(self):
- """Test that messages queue when tree is busy."""
- manager = TreeQueueManager()
- processing_started = asyncio.Event()
- processing_complete = asyncio.Event()
-
- async def slow_processor(node_id, node):
- processing_started.set()
- await processing_complete.wait()
-
- # Create tree with root
- root_incoming = IncomingMessage(
- text="Root",
- chat_id="1",
- user_id="1",
- message_id="root",
- platform="test",
- )
- await manager.create_tree("root", root_incoming, "s1")
-
- # Start processing root
- was_queued = await manager.enqueue("root", slow_processor)
- assert was_queued is False
-
- # Wait for processing to start
- await processing_started.wait()
-
- # Add a child
- child_incoming = IncomingMessage(
- text="Child",
- chat_id="1",
- user_id="1",
- message_id="child",
- platform="test",
- reply_to_message_id="root",
- )
- await manager.add_to_tree("root", "child", child_incoming, "s2")
-
- # Try to enqueue child - should be queued since tree is busy
- was_queued = await manager.enqueue("child", slow_processor)
- assert was_queued is True
- assert manager.get_queue_size("child") == 1
-
- # Cleanup
- processing_complete.set()
-
- @pytest.mark.asyncio
- async def test_cancel_tree(self):
- """Test cancelling a tree."""
- manager = TreeQueueManager()
- processing_complete = asyncio.Event()
-
- async def slow_processor(node_id, node):
- await processing_complete.wait()
-
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="1",
- message_id="m1",
- platform="test",
- )
- await manager.create_tree("m1", incoming, "s1")
- await manager.enqueue("m1", slow_processor)
-
- # Cancel
- cancelled = await manager.cancel_tree("m1")
- assert len(cancelled) == 1
-
- processing_complete.set()
-
- @pytest.mark.asyncio
- async def test_cancel_tree_waits_for_current_task_cleanup(self):
- """cancel_tree returns only after the cancelled task cleanup runs."""
- manager = TreeQueueManager()
- started = asyncio.Event()
- cleanup_done = asyncio.Event()
-
- async def slow_processor(node_id, node):
- started.set()
- try:
- await asyncio.sleep(60)
- except asyncio.CancelledError:
- cleanup_done.set()
- raise
-
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="1",
- message_id="m1",
- platform="test",
- )
- await manager.create_tree("m1", incoming, "s1")
- await manager.enqueue("m1", slow_processor)
- await started.wait()
-
- cancelled = await manager.cancel_tree("m1", reason=CancellationReason.STOP)
-
- assert [entry.node.node_id for entry in cancelled] == ["m1"]
- assert [entry.ui_owner for entry in cancelled] == [CancellationUiOwner.RUNNER]
- assert get_cancel_reason(cancelled[0].node) is CancellationReason.STOP
- assert cleanup_done.is_set()
-
- @pytest.mark.asyncio
- async def test_cancel_node_waits_for_current_task_cleanup(self):
- """cancel_node waits when the target node is actively running."""
- manager = TreeQueueManager()
- started = asyncio.Event()
- cleanup_done = asyncio.Event()
-
- async def slow_processor(node_id, node):
- started.set()
- try:
- await asyncio.sleep(60)
- except asyncio.CancelledError:
- cleanup_done.set()
- raise
-
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="1",
- message_id="m1",
- platform="test",
- )
- await manager.create_tree("m1", incoming, "s1")
- await manager.enqueue("m1", slow_processor)
- await started.wait()
-
- cancelled = await manager.cancel_node("m1", reason=CancellationReason.STOP)
-
- assert [entry.node.node_id for entry in cancelled] == ["m1"]
- assert [entry.ui_owner for entry in cancelled] == [CancellationUiOwner.RUNNER]
- assert get_cancel_reason(cancelled[0].node) is CancellationReason.STOP
- assert cleanup_done.is_set()
-
- @pytest.mark.asyncio
- async def test_cancel_branch(self):
- """Test cancel_branch cancels only nodes in subtree."""
- 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",
- )
- tree, _ = await manager.add_to_tree("root", "child", child_incoming, "s2")
-
- sibling_incoming = IncomingMessage(
- text="Sibling",
- chat_id="1",
- user_id="1",
- message_id="sibling",
- platform="test",
- reply_to_message_id="root",
- )
- await manager.add_to_tree("root", "sibling", sibling_incoming, "s3")
-
- cancelled = await manager.cancel_branch("child")
- assert len(cancelled) == 1
- assert cancelled[0].node.node_id == "child"
- assert cancelled[0].ui_owner is CancellationUiOwner.WORKFLOW
-
- child_node = tree.get_node("child")
- assert child_node is not None
- assert child_node.state == MessageState.ERROR
-
- sibling_node = tree.get_node("sibling")
- assert sibling_node is not None
- assert sibling_node.state == MessageState.PENDING
-
- @pytest.mark.asyncio
- async def test_cancel_branch_waits_for_current_task_cleanup(self):
- """cancel_branch waits when the active node is inside the branch."""
- manager = TreeQueueManager()
- started = asyncio.Event()
- cleanup_done = asyncio.Event()
-
- async def slow_processor(node_id, node):
- started.set()
- try:
- await asyncio.sleep(60)
- except asyncio.CancelledError:
- cleanup_done.set()
- raise
-
- 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")
- await manager.enqueue("child", slow_processor)
- await started.wait()
-
- cancelled = await manager.cancel_branch("child")
-
- assert [entry.node.node_id for entry in cancelled] == ["child"]
- assert [entry.ui_owner for entry in cancelled] == [CancellationUiOwner.RUNNER]
- assert cleanup_done.is_set()
-
- @pytest.mark.asyncio
- async def test_cancel_all_waits_for_current_task_cleanup_across_trees(self):
- """cancel_all waits for active task cleanup in every tree."""
- manager = TreeQueueManager()
- started: set[str] = set()
- cleanup_done: set[str] = set()
- all_started = asyncio.Event()
-
- async def slow_processor(node_id, node):
- started.add(node_id)
- if started == {"a", "b"}:
- all_started.set()
- try:
- await asyncio.sleep(60)
- except asyncio.CancelledError:
- cleanup_done.add(node_id)
- raise
-
- for node_id in ("a", "b"):
- incoming = IncomingMessage(
- text="Test",
- chat_id="1",
- user_id="1",
- message_id=node_id,
- platform="test",
- )
- await manager.create_tree(node_id, incoming, f"s_{node_id}")
- await manager.enqueue(node_id, slow_processor)
- await all_started.wait()
-
- cancelled = await manager.cancel_all(reason=CancellationReason.STOP)
-
- assert {entry.node.node_id for entry in cancelled} == {"a", "b"}
- assert {entry.ui_owner for entry in cancelled} == {CancellationUiOwner.RUNNER}
- assert {get_cancel_reason(entry.node) for entry in cancelled} == {
- CancellationReason.STOP
- }
- assert cleanup_done == {"a", "b"}
-
- @pytest.mark.asyncio
- async def test_cancel_task_drain_timeout_is_bounded(self, monkeypatch):
- """Cancellation drain returns when a task refuses to finish cleanup."""
- monkeypatch.setattr(tree_manager_module, "CANCEL_TASK_DRAIN_TIMEOUT_S", 0.01)
- started = asyncio.Event()
- cleanup_started = asyncio.Event()
- cleanup_release = asyncio.Event()
-
- async def stubborn_task():
- started.set()
- try:
- await asyncio.sleep(60)
- except asyncio.CancelledError:
- cleanup_started.set()
- await cleanup_release.wait()
- raise
-
- task = asyncio.create_task(stubborn_task())
- await started.wait()
- task.cancel()
- await cleanup_started.wait()
-
- start = asyncio.get_running_loop().time()
- try:
- await tree_manager_module._drain_cancelled_tasks([task])
- elapsed = asyncio.get_running_loop().time() - start
- assert not task.done()
- finally:
- cleanup_release.set()
- if not task.done():
- with contextlib.suppress(asyncio.CancelledError):
- await task
-
- assert elapsed < 0.5
-
- @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 [entry.node.node_id for entry in cancelled] == ["queued_first"]
- assert [entry.ui_owner for entry in cancelled] == [CancellationUiOwner.WORKFLOW]
- 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 [entry.node.node_id for entry in cancelled] == ["queued_first"]
- assert [entry.ui_owner for entry in cancelled] == [CancellationUiOwner.WORKFLOW]
- 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."""
- 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",
- )
- tree, _ = await manager.add_to_tree("root", "child", child_incoming, "s2")
-
- removed, root_id, removed_entire = await manager.remove_branch("child")
-
- assert len(removed) == 1
- assert removed[0].node_id == "child"
- assert root_id == "root"
- assert removed_entire is False
- assert manager.get_tree_for_node("child") is None
- assert manager.get_tree("root") is not None
- 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."""
- 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")
-
- removed, root_id, removed_entire = await manager.remove_branch("root")
-
- assert len(removed) == 1
- assert root_id == "root"
- assert removed_entire is True
- 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."""
-
- def test_save_and_get_tree(self, tmp_path):
- """Test saving and retrieving a tree."""
- from free_claude_code.messaging.session import SessionStore
-
- store = SessionStore(storage_path=str(tmp_path / "sessions.json"))
-
- tree_data = {
- "root_id": "root_1",
- "nodes": {
- "root_1": {
- "node_id": "root_1",
- "state": "completed",
- "session_id": "sess_abc",
- }
- },
- }
-
- snapshot = TreeSnapshot.from_json(tree_data)
- assert snapshot is not None
- store.save_tree_snapshot(snapshot)
-
- retrieved = store.get_tree_snapshot("root_1")
- assert retrieved is not None
- assert retrieved.root_id == "root_1"
-
- def test_get_tree_by_root_id(self, tmp_path):
- """Test getting tree by root ID and node mapping."""
- from free_claude_code.messaging.session import SessionStore
-
- store = SessionStore(storage_path=str(tmp_path / "sessions.json"))
-
- tree_data = {
- "root_id": "root",
- "nodes": {
- "root": {"node_id": "root"},
- "child": {"node_id": "child"},
- },
- }
-
- snapshot = TreeSnapshot.from_json(tree_data)
- assert snapshot is not None
- store.save_tree_snapshot(snapshot)
-
- retrieved = store.get_tree_snapshot("root")
- assert retrieved is not None
- assert retrieved.root_id == "root"
- assert (
- store.load_conversation_snapshot().derive_node_to_tree()["child"] == "root"
- )
+_SCOPE = MessageScope(platform="telegram", chat_id="chat")
+
+
+def _root() -> MessageNode:
+ return MessageNode(
+ node_id="root",
+ scope=_SCOPE,
+ prompt="prompt root",
+ status_message_id="status-root",
+ )
+
+
+def _add(
+ graph: MessageTreeGraph,
+ node_id: str,
+ status_message_id: str,
+ parent_id: str,
+) -> MessageNode:
+ return graph.add_node(
+ node_id=node_id,
+ scope=_SCOPE,
+ prompt=f"prompt {node_id}",
+ status_message_id=status_message_id,
+ parent_id=parent_id,
+ )
+
+
+def test_node_snapshot_round_trip_preserves_execution_state_only() -> None:
+ node = _root()
+ node.children_ids.extend(["child-a", "child-b"])
+ node.update_state(MessageState.ERROR)
+ node.update_state(MessageState.COMPLETED, session_id="session-root")
+
+ snapshot = node_to_snapshot(node)
+ restored = node_from_snapshot(snapshot, _SCOPE)
+
+ assert restored.node_id == "root"
+ assert restored.scope == _SCOPE
+ assert restored.prompt == ""
+ assert restored.status_message_id == "status-root"
+ assert restored.state is MessageState.COMPLETED
+ assert restored.session_id == "session-root"
+ assert restored.children_ids == []
+ assert "children_ids" not in snapshot
+ assert "created_at" not in snapshot
+ assert "completed_at" not in snapshot
+ assert "error_message" not in snapshot
+
+
+def test_graph_snapshot_round_trip_preserves_links_and_status_lookup() -> None:
+ graph = MessageTreeGraph(_root())
+ child = _add(graph, "child", "status-child", "root")
+ _add(graph, "grandchild", "status-grandchild", "child")
+ child.update_state(MessageState.COMPLETED, session_id="session-child")
+
+ restored = MessageTreeGraph.from_snapshot(graph.snapshot())
+ parent = restored.get_parent("grandchild")
+ status_child = restored.find_node_by_status_message("status-child")
+
+ assert restored.root_id == "root"
+ assert parent is not None
+ assert parent.node_id == "child"
+ assert restored.get_parent_session_id("grandchild") == "session-child"
+ assert status_child is not None
+ assert status_child.node_id == "child"
+ assert restored.get_descendants("root") == ["root", "child", "grandchild"]
+
+
+def test_graph_restore_normalizes_numeric_ids_to_string_references() -> None:
+ graph = MessageTreeGraph(_root())
+ _add(graph, "child", "status-child", "root")
+ snapshot = graph.snapshot()
+ snapshot.nodes["child"]["node_id"] = 2
+ snapshot.nodes["child"]["status_message_id"] = 123
+ snapshot.nodes["child"]["parent_id"] = "root"
+ snapshot.nodes["2"] = snapshot.nodes.pop("child")
+
+ restored = MessageTreeGraph.from_snapshot(snapshot)
+
+ child = restored.find_node_by_status_message("123")
+ assert child is not None and child.node_id == "2"
+
+
+def test_graph_rejects_duplicate_node_and_status_identity() -> None:
+ graph = MessageTreeGraph(_root())
+ _add(graph, "child", "status-child", "root")
+
+ with pytest.raises(ValueError, match="already exists"):
+ _add(graph, "child", "status-other", "root")
+ with pytest.raises(ValueError, match="already exists"):
+ _add(graph, "other", "status-child", "root")
+
+
+def test_graph_remove_branch_removes_descendants_and_status_lookups() -> None:
+ graph = MessageTreeGraph(_root())
+ _add(graph, "branch", "status-branch", "root")
+ _add(graph, "leaf", "status-leaf", "branch")
+ _add(graph, "sibling", "status-sibling", "root")
+
+ graph.remove_branch("branch")
+
+ assert graph.get_node("branch") is None
+ assert graph.get_node("leaf") is None
+ assert graph.find_node_by_status_message("status-branch") is None
+ assert graph.find_node_by_status_message("status-leaf") is None
+ assert graph.get_descendants("root") == ["root", "sibling"]
+
+
+def test_tree_snapshot_rejects_invalid_wire_shapes() -> None:
+ assert TreeSnapshot.from_json(None) is None
+ assert TreeSnapshot.from_json({"root_id": "root", "nodes": []}) is None
+ assert TreeSnapshot.from_json({"nodes": {}}) is None
+
+
+def test_node_queue_is_unique_fifo_and_supports_atomic_removal() -> None:
+ queue = MessageNodeQueue()
+
+ assert queue.put("a") is True
+ assert queue.put("b") is True
+ assert queue.put("a") is False
+ assert queue.items() == ("a", "b")
+ assert queue.remove("a") is True
+ assert queue.remove("a") is False
+ assert queue.items() == ("b",)
+ assert queue.pop() == "b"
+ assert queue.pop() is None
+
+ assert queue.put("c") is True
+ assert queue.put("d") is True
+ assert queue.drain() == ("c", "d")
+ assert queue.items() == ()
diff --git a/tests/messaging/test_tree_repository.py b/tests/messaging/test_tree_repository.py
index 4c11291a..18e817c4 100644
--- a/tests/messaging/test_tree_repository.py
+++ b/tests/messaging/test_tree_repository.py
@@ -1,132 +1,194 @@
-from unittest.mock import MagicMock
-
-import pytest
-
-from free_claude_code.messaging.models import IncomingMessage
-from free_claude_code.messaging.trees import MessageNode, MessageTree
-from free_claude_code.messaging.trees.repository import TreeRepository
+"""Persistence and restored-manager contracts for messaging trees."""
+import asyncio
-def repository():
- return TreeRepository()
-
+import pytest
-def sample_tree():
- incoming = IncomingMessage(
- text="root",
- chat_id="c1",
- user_id="u1",
- message_id="root_id",
+from free_claude_code.messaging.models import IncomingMessage, MessageScope
+from free_claude_code.messaging.trees import (
+ ConversationSnapshot,
+ MessageState,
+ NodeClaim,
+ TreeIdentity,
+ TreeQueueManager,
+ TreeSnapshot,
+)
+from free_claude_code.messaging.trees.node import MessageNode
+from free_claude_code.messaging.trees.snapshot import node_to_snapshot
+
+TELEGRAM_CHAT = MessageScope(platform="telegram", chat_id="chat")
+ROOT_IDENTITY = TreeIdentity(scope=TELEGRAM_CHAT, root_id="root")
+
+
+def _incoming(node_id: str, *, reply_to: str | None = None) -> IncomingMessage:
+ return IncomingMessage(
+ text=f"prompt {node_id}",
+ chat_id="chat",
+ user_id="user",
+ message_id=node_id,
platform="telegram",
+ reply_to_message_id=reply_to,
)
- node = MessageNode(node_id="root_id", incoming=incoming, status_message_id="s1")
- return MessageTree(node)
-
-
-def test_add_and_get_tree(repository, sample_tree):
- repository.add_tree("root_id", sample_tree)
-
- assert repository.get_tree("root_id") == sample_tree
- assert repository.get_tree_for_node("root_id") == sample_tree
- assert repository.has_node("root_id")
-
-
-def test_get_tree_nonexistent(repository):
- assert repository.get_tree("none") is None
- assert repository.get_tree_for_node("none") is None
-
-
-def test_register_node(repository, sample_tree):
- repository.add_tree("root_id", sample_tree)
- repository.register_node("child_id", "root_id")
-
- assert repository.get_tree_for_node("child_id") == sample_tree
- assert repository.has_node("child_id")
-
-
-def test_get_node(repository, sample_tree):
- repository.add_tree("root_id", sample_tree)
- node = repository.get_node("root_id")
-
- assert node is not None
- assert node.node_id == "root_id"
- assert repository.get_node("none") is None
-
-
-def test_is_tree_busy(repository, sample_tree):
- repository.add_tree("root_id", sample_tree)
- assert repository.is_tree_busy("root_id") is False
-
- sample_tree._is_processing = True
- assert repository.is_tree_busy("root_id") is True
- assert repository.is_node_tree_busy("root_id") is True
-def test_get_queue_size(repository, sample_tree):
- repository.add_tree("root_id", sample_tree)
- assert repository.get_queue_size("root_id") == 0
-
- # We can't easily put items in asyncio.Queue without async,
- # but we can mock it for this unit test if needed, or just skip if it's too complex.
- # Actually, we can use a mock queue since this is a unit test of the repository wrapper.
- sample_tree._queue = MagicMock()
- sample_tree._queue.qsize.return_value = 5
-
- assert repository.get_queue_size("root_id") == 5
-
+async def _wait_for_no_tasks(manager: TreeQueueManager) -> None:
+ loop = asyncio.get_running_loop()
+ for _ in range(20):
+ if manager.task_count() == 0:
+ return
+ checkpoint = asyncio.Event()
+ loop.call_soon(checkpoint.set)
+ await checkpoint.wait()
+ assert manager.task_count() == 0
+
+
+def _interrupted_conversation() -> ConversationSnapshot:
+ root = MessageNode(
+ node_id="root",
+ scope=TELEGRAM_CHAT,
+ prompt="prompt root",
+ status_message_id="status-root",
+ state=MessageState.COMPLETED,
+ session_id="session-root",
+ children_ids=["pending", "failed"],
+ )
+ pending = MessageNode(
+ node_id="pending",
+ scope=TELEGRAM_CHAT,
+ prompt="prompt pending",
+ status_message_id="status-pending",
+ parent_id="root",
+ state=MessageState.PENDING,
+ children_ids=["running"],
+ )
+ running = MessageNode(
+ node_id="running",
+ scope=TELEGRAM_CHAT,
+ prompt="prompt running",
+ status_message_id="status-running",
+ parent_id="pending",
+ state=MessageState.IN_PROGRESS,
+ )
+ failed = MessageNode(
+ node_id="failed",
+ scope=TELEGRAM_CHAT,
+ prompt="prompt failed",
+ status_message_id="status-failed",
+ parent_id="root",
+ state=MessageState.ERROR,
+ )
+ snapshot = TreeSnapshot(
+ scope=TELEGRAM_CHAT,
+ root_id="root",
+ nodes={
+ node.node_id: node_to_snapshot(node)
+ for node in (root, pending, running, failed)
+ },
+ )
+ return ConversationSnapshot(trees={snapshot.identity: snapshot})
-def test_resolve_parent_node_id(repository, sample_tree):
- repository.add_tree("root_id", sample_tree)
- repository.register_node("s1", "root_id")
- # 1. Direct node match
- assert repository.resolve_parent_node_id("root_id") == "root_id"
+async def test_restore_reconciles_interrupted_nodes_before_manager_exposure() -> None:
+ processed: list[str] = []
+
+ async def process(claim: NodeClaim) -> None:
+ processed.append(claim.node.node_id)
+
+ manager = TreeQueueManager.from_snapshot(_interrupted_conversation(), process)
+
+ assert len(manager.restored_stale_targets) == 2
+ assert manager.restored_snapshot is not None
+ assert manager.restored_snapshot == await manager.snapshot()
+ assert manager.task_count() == 0
+ assert processed == []
+
+ root = await manager.get_node(TELEGRAM_CHAT, "root")
+ pending = await manager.get_node(TELEGRAM_CHAT, "pending")
+ running = await manager.get_node(TELEGRAM_CHAT, "status-running")
+ failed = await manager.get_node(TELEGRAM_CHAT, "failed")
+ assert root is not None and root.state is MessageState.COMPLETED
+ assert root.session_id == "session-root"
+ assert pending is not None and pending.state is MessageState.ERROR
+ assert running is not None and running.state is MessageState.ERROR
+ assert failed is not None and failed.state is MessageState.ERROR
+ assert await manager.resolve_node_id(TELEGRAM_CHAT, "status-pending") == "pending"
+ assert {
+ (target.scope, target.node_id) for target in manager.restored_stale_targets
+ } == {
+ (TELEGRAM_CHAT, "pending"),
+ (TELEGRAM_CHAT, "running"),
+ }
+
+ normalized = await manager.snapshot()
+ normalized_tree = normalized.get_tree(ROOT_IDENTITY)
+ assert normalized_tree is not None
+ assert normalized_tree.nodes["pending"]["state"] == "error"
+ assert normalized_tree.nodes["running"]["state"] == "error"
+ assert normalized_tree.nodes["failed"]["state"] == "error"
+ assert all("error_message" not in node for node in normalized_tree.nodes.values())
+
+
[email protected]("corruption", ["cross_scope", "duplicate_reference"])
+def test_restore_rejects_tree_that_violates_scoped_reference_invariants(
+ corruption: str,
+) -> None:
+ snapshot = _interrupted_conversation()
+ tree = snapshot.get_tree(ROOT_IDENTITY)
+ assert tree is not None
+ if corruption == "cross_scope":
+ tree.nodes["pending"]["incoming"] = {
+ "platform": "telegram",
+ "chat_id": "other-chat",
+ }
+ else:
+ tree.nodes["failed"]["status_message_id"] = "status-pending"
- # 2. Status message match
- # find_node_by_status_message is used inside resolve_parent_node_id
- # sample_tree has root_id node with status_message_id "s1"
- assert repository.resolve_parent_node_id("s1") == "root_id"
+ manager = TreeQueueManager.from_snapshot(snapshot, lambda _claim: asyncio.sleep(0))
- # 3. No match
- assert repository.resolve_parent_node_id("unknown") is None
+ assert manager.get_tree_count() == 0
+ assert manager.restored_snapshot == ConversationSnapshot()
@pytest.mark.asyncio
-async def test_get_pending_children(repository, sample_tree):
- repository.add_tree("root_id", sample_tree)
-
- child_incoming = IncomingMessage(
- text="child",
- chat_id="c1",
- user_id="u1",
- message_id="child_id",
- platform="telegram",
+async def test_claim_state_and_session_updates_produce_detached_snapshots() -> None:
+ release = asyncio.Event()
+ started = asyncio.Event()
+
+ async def process(_claim: NodeClaim) -> None:
+ started.set()
+ await release.wait()
+
+ manager = TreeQueueManager(process)
+ decision = await manager.admit(_incoming("root"), "status-root")
+ assert decision.claim is not None
+ await started.wait()
+
+ session_snapshot = await manager.record_session(decision.claim, "session-root")
+ completed_snapshot = await manager.complete_claim(
+ decision.claim,
+ "session-root",
)
- await sample_tree.add_node("child_id", child_incoming, "s2", "root_id")
- repository.register_node("child_id", "root_id")
-
- pending = repository.get_pending_children("root_id")
- assert len(pending) == 1
- assert pending[0].node_id == "child_id"
-
-
-def test_snapshot_round_trip(repository, sample_tree):
- repository.add_tree("root_id", sample_tree)
- snapshot = repository.snapshot()
-
- assert "root_id" in snapshot.trees
- assert snapshot.derive_node_to_tree()["root_id"] == "root_id"
- new_repo = TreeRepository.from_snapshot(snapshot)
- tree = new_repo.get_tree("root_id")
- assert tree is not None
- assert tree.root_id == "root_id"
- assert new_repo.get_tree_for_node("root_id") == tree
-
-
-def test_all_trees(repository, sample_tree):
- repository.add_tree("root_id", sample_tree)
- assert len(repository.all_trees()) == 1
- assert repository.tree_ids() == ["root_id"]
+ assert session_snapshot is not None
+ assert session_snapshot.nodes["root"]["state"] == "in_progress"
+ assert session_snapshot.nodes["root"]["session_id"] == "session-root"
+ assert completed_snapshot is not None
+ assert completed_snapshot.nodes["root"]["state"] == "completed"
+ assert completed_snapshot.nodes["root"]["session_id"] == "session-root"
+
+ assert decision.snapshot is not None
+ decision.snapshot.nodes["root"]["state"] = "mutated-copy"
+ view = await manager.get_node(TELEGRAM_CHAT, "status-root")
+ assert view is not None and view.state is MessageState.COMPLETED
+ assert view.session_id == "session-root"
+ assert await manager.get_message_ids_for_chat("telegram", "chat") == {
+ "root",
+ "status-root",
+ }
+
+ release.set()
+ await _wait_for_no_tasks(manager)
+ assert await manager.snapshot() == ConversationSnapshot(
+ trees={ROOT_IDENTITY: completed_snapshot}
+ )
diff --git a/tests/messaging/test_voice_handlers.py b/tests/messaging/test_voice_handlers.py
index a33d77a8..9584f582 100644
--- a/tests/messaging/test_voice_handlers.py
+++ b/tests/messaging/test_voice_handlers.py
@@ -113,7 +113,6 @@ async def test_telegram_voice_success_invokes_handler(telegram_platform):
incoming = handler.call_args[0][0]
assert incoming.text == "Hello from voice"
assert incoming.chat_id == "6789"
- assert incoming.user_id == "12345"
assert incoming.platform == "telegram"
assert incoming.status_message_id == "999"
diff --git a/tests/messaging/test_voice_services.py b/tests/messaging/test_voice_services.py
index b97fe730..d6d79bcb 100644
--- a/tests/messaging/test_voice_services.py
+++ b/tests/messaging/test_voice_services.py
@@ -1,24 +1,48 @@
import pytest
+from free_claude_code.messaging.models import MessageScope
from free_claude_code.messaging.voice import PendingVoiceRegistry
+TELEGRAM_CHAT = MessageScope(platform="telegram", chat_id="chat")
+DISCORD_CHAT = MessageScope(platform="discord", chat_id="chat")
+
@pytest.mark.asyncio
async def test_pending_voice_registry_tracks_voice_and_status_ids():
registry = PendingVoiceRegistry()
- await registry.register("chat", "voice-1", "status-1")
+ await registry.register(TELEGRAM_CHAT, "voice-1", "status-1")
+
+ assert await registry.is_pending(TELEGRAM_CHAT, "voice-1") is True
+ assert await registry.cancel(TELEGRAM_CHAT, "status-1") == (
+ "voice-1",
+ "status-1",
+ )
+ assert await registry.is_pending(TELEGRAM_CHAT, "voice-1") is False
+
+
+async def test_pending_voice_registry_isolates_platform_scopes():
+ registry = PendingVoiceRegistry()
+ await registry.register(DISCORD_CHAT, "voice-1", "status-1")
+ await registry.register(TELEGRAM_CHAT, "voice-1", "status-1")
- assert await registry.is_pending("chat", "voice-1") is True
- assert await registry.cancel("chat", "status-1") == ("voice-1", "status-1")
- assert await registry.is_pending("chat", "voice-1") is False
+ assert await registry.cancel(TELEGRAM_CHAT, "voice-1") == (
+ "voice-1",
+ "status-1",
+ )
+ assert await registry.is_pending(DISCORD_CHAT, "voice-1") is True
+ assert await registry.cancel(DISCORD_CHAT, "voice-1") == (
+ "voice-1",
+ "status-1",
+ )
@pytest.mark.asyncio
async def test_pending_voice_registry_complete_removes_entries():
registry = PendingVoiceRegistry()
- await registry.register("chat", "voice-1", "status-1")
- await registry.complete("chat", "voice-1", "status-1")
+ await registry.register(TELEGRAM_CHAT, "voice-1", "status-1")
+ await registry.complete(TELEGRAM_CHAT, "voice-1", "status-1")
- assert await registry.cancel("chat", "voice-1") is None
+ assert await registry.cancel(TELEGRAM_CHAT, "voice-1") is None
diff --git a/uv.lock b/uv.lock
index 8d7d1373..ea576b03 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "3.4.22"
+version = "3.4.23"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },