dheraingoud's picture
sync: upstream 9194f15 + custom addons (KeyRotator, RotatingChatTransport, sol/terra/luna, ScannerTrap, health, Py3.12 compat)
e99df76
Raw History Blame Contribute Delete
26.2 kB
from __future__ import annotations
"""Messaging workflow coordinator for Discord and Telegram prompts."""
import asyncio
from collections.abc import Coroutine
from typing import Any
from loguru import logger
from free_claude_code.core.trace import trace_event
from .command_context import ReplyClearResult, StopOutcome
from .command_dispatcher import parse_command_base
from .managed_protocols import ManagedClaudeSessionManagerProtocol
from .models import AdmissionToken, IncomingMessage, MessageScope
from .node_runner import MessagingNodeRunner
from .platforms.ports import (
MessagingStartupNotice,
OutboundMessenger,
VoiceCancellation,
)
from .rendering.profiles import build_rendering_profile
from .safe_diagnostics import format_exception_for_log
from .transcript import RenderCtx
from .trees import (
CancellationReason,
CancellationResult,
CancellationUiOwner,
ConversationSnapshot,
FailureResult,
MessagingStore,
NodeUiTarget,
QueueDecision,
ReplyTarget,
TreeQueueManager,
)
from .turn_intake import MessagingTurnIntake
from .voice import VoiceCancellationResult
async def _finish_owned_operation[T](
operation: Coroutine[Any, Any, T],
*,
name: str,
) -> T:
"""Finish owned work, preserving its failures before caller cancellation."""
task = asyncio.create_task(operation, name=name)
current = asyncio.current_task()
cancellation: asyncio.CancelledError | None = None
while not task.done():
try:
await asyncio.shield(task)
except asyncio.CancelledError as exc:
if current is not None and current.cancelling():
cancellation = cancellation or exc
except Exception:
break
# Task.result() raises the owned operation's failure. Caller cancellation
# is restored only after successful completion.
result = task.result()
if cancellation is not None:
raise cancellation
return result
def _stop_outcome(
voices: tuple[VoiceCancellationResult, ...],
cancellation: CancellationResult,
) -> StopOutcome:
"""Summarize distinct stopped owners and whether existing status UI covers them."""
status_coverage: dict[tuple[MessageScope, str], bool] = {}
for voice in voices:
key = (voice.scope, voice.voice_message_id)
status_coverage[key] = (
status_coverage.get(key, False) or voice.status_message_id is not None
)
for effect in cancellation.effects:
status_coverage[(effect.node.scope, effect.node.node_id)] = True
return StopOutcome(
cancelled_count=len(status_coverage),
status_feedback_scopes=frozenset(
scope for (scope, _owner_id), covered in status_coverage.items() if covered
),
fallback_required=any(not covered for covered in status_coverage.values()),
)
class MessagingWorkflow:
"""Own messaging state transitions and their external side effects."""
def __init__(
self,
outbound: OutboundMessenger,
cli_manager: ManagedClaudeSessionManagerProtocol,
session_store: MessagingStore,
*,
platform_name: str | None = None,
voice_cancellation: VoiceCancellation | None = None,
debug_platform_edits: bool = False,
debug_subagent_stack: bool = False,
log_raw_cli_diagnostics: bool = False,
log_messaging_error_details: bool = False,
) -> None:
self.platform_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._rendering_profile = build_rendering_profile(self.platform_name)
self._state_lock = asyncio.Lock()
self._stop_generation = 0
self._clear_generations: dict[MessageScope, int] = {}
self._pending_restored_status_targets: tuple[NodeUiTarget, ...] = ()
self._tree_queue: TreeQueueManager
self.node_runner = MessagingNodeRunner(
platform_name=self.platform_name,
outbound=outbound,
cli_manager=cli_manager,
get_tree_queue=lambda: self._tree_queue,
format_status=self.format_status,
get_parse_mode=self._parse_mode,
get_render_ctx=self.get_render_ctx,
get_limit_chars=self._get_limit_chars,
debug_platform_edits=debug_platform_edits,
debug_subagent_stack=debug_subagent_stack,
log_raw_cli_diagnostics=log_raw_cli_diagnostics,
log_messaging_error_details=log_messaging_error_details,
)
self.turn_intake = MessagingTurnIntake(
platform_name=self.platform_name,
outbound=outbound,
session_store=session_store,
command_context=self,
resolve_reply=self.resolve_reply,
admit_turn=self._admit_turn_if_current,
format_status=self.format_status,
get_parse_mode=self._parse_mode,
)
self._tree_queue = self._build_tree_queue()
def _build_tree_queue(
self, snapshot: ConversationSnapshot | None = None
) -> TreeQueueManager:
if snapshot is None:
return TreeQueueManager(
self.node_runner.process_node,
store=self.session_store,
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,
log_messaging_error_details=self._log_messaging_error_details,
)
return TreeQueueManager.from_snapshot(
snapshot,
self.node_runner.process_node,
store=self.session_store,
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,
log_messaging_error_details=self._log_messaging_error_details,
)
def format_status(self, emoji: str, label: str, suffix: str | None = None) -> str:
return self._rendering_profile.format_status(emoji, label, suffix)
def _parse_mode(self) -> str | None:
return self._rendering_profile.parse_mode
def get_render_ctx(self) -> RenderCtx:
return self._rendering_profile.render_ctx
def _get_limit_chars(self) -> int:
return self._rendering_profile.limit_chars
@property
def tree_queue(self) -> TreeQueueManager:
"""Expose the manager facade for diagnostics and smoke tests."""
return self._tree_queue
async def restore(self) -> None:
"""Restore and reconcile persisted conversations before platform start."""
snapshot = await self.session_store.load_conversation_snapshot()
if snapshot.is_empty:
return
logger.info("Restoring {} conversation trees...", len(snapshot.trees))
self._tree_queue = self._build_tree_queue(snapshot)
normalized = self._tree_queue.restored_snapshot
if normalized is not None and normalized != snapshot:
await self.session_store.commit_trees(
tuple(
tree
for tree in normalized.trees.values()
if self.platform_name == "messaging"
or tree.scope.platform == self.platform_name
),
removed=tuple(snapshot.trees.keys() - normalized.trees.keys()),
)
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__,
)
async def publish_startup_notice(self, notice: MessagingStartupNotice) -> None:
"""Publish one notice, then transfer its receipt to clear ownership."""
scope = MessageScope(platform=self.platform_name, chat_id=notice.chat_id)
async with self._state_lock:
clear_generation = self._clear_generations.get(scope, 0)
try:
message_id = await self.outbound.queue_send_message(
notice.chat_id,
self.format_status(
"🚀",
"Claude Code Proxy is online!",
f"({notice.transport_label})",
),
parse_mode=self._parse_mode(),
fire_and_forget=False,
)
except Exception as exc:
logger.warning(
"Could not publish messaging startup notice: {}",
format_exception_for_log(
exc,
log_full_message=self._log_messaging_error_details,
),
)
return
if not message_id:
return
publisher_task = asyncio.current_task()
await _finish_owned_operation(
self._finalize_startup_notice(
notice,
message_id,
clear_generation,
publisher_task,
),
name="messaging-finalize-startup-notice",
)
async def _finalize_startup_notice(
self,
notice: MessagingStartupNotice,
message_id: str,
clear_generation: int,
publisher_task: asyncio.Task[Any] | None,
) -> None:
"""Commit one delivery receipt or compensate it outside the state lock."""
async with self._state_lock:
must_discard = (
publisher_task is not None and publisher_task.cancelling() > 0
) or clear_generation != self._clear_generations.get(
MessageScope(platform=self.platform_name, chat_id=notice.chat_id), 0
)
if not must_discard:
must_discard = not await self.record_outgoing_message(
self.platform_name,
notice.chat_id,
message_id,
"startup",
)
if must_discard:
await self._discard_startup_notice(notice.chat_id, message_id)
async def _discard_startup_notice(
self,
chat_id: str,
message_id: str,
) -> None:
"""Delete an uncommitted notice or retain its ID for a later clear."""
try:
await self.outbound.queue_delete_messages(
chat_id,
[message_id],
fire_and_forget=False,
)
except Exception as exc:
logger.warning(
"Could not discard messaging startup notice: {}",
format_exception_for_log(
exc,
log_full_message=self._log_messaging_error_details,
),
)
async with self._state_lock:
tracked = await self.record_outgoing_message(
self.platform_name,
chat_id,
message_id,
"startup",
)
if not tracked:
logger.warning(
"Messaging startup notice could neither be deleted nor tracked"
)
return
async with self._state_lock:
await self.forget_tracked_message_ids(
self.platform_name,
chat_id,
{message_id},
)
async def close(self) -> None:
"""Finish every owned task and durable write before releasing delivery."""
await self._cancel_all_pending_voices()
async with self._state_lock:
self._stop_generation += 1
result = await self._tree_queue.shutdown()
self._apply_cancellation_result(result)
await self.cli_manager.stop_all()
await self._tree_queue.wait_idle()
async def handle_message(self, incoming: IncomingMessage) -> None:
"""Handle one platform message."""
trace_event(
stage="ingress",
event="turn.received",
source=self.platform_name,
chat_id=incoming.chat_id,
platform_message_id=incoming.message_id,
reply_to_message_id=incoming.reply_to_message_id,
thread_id=incoming.message_thread_id,
message_text=incoming.text or "",
)
with logger.contextualize(
chat_id=incoming.chat_id,
node_id=incoming.message_id,
):
is_standalone_clear = (
parse_command_base(incoming.text) == "/clear"
and not incoming.is_reply()
)
async with self._state_lock:
admission_token = AdmissionToken(
stop_generation=self._stop_generation,
clear_generation=self._clear_generations.get(incoming.scope, 0),
)
if not is_standalone_clear:
await self._record_incoming_message(incoming)
try:
await self.turn_intake.handle_message(
incoming,
admission_token=admission_token,
)
except BaseException:
if is_standalone_clear:
async with self._state_lock:
await self._record_incoming_message(incoming)
raise
async def resolve_reply(
self,
scope: MessageScope,
reference_id: str,
) -> ReplyTarget | None:
return await self._tree_queue.resolve_reply(scope, reference_id)
async def _admit_turn_if_current(
self,
incoming: IncomingMessage,
status_message_id: str,
parent_reference_id: str | None,
admission_token: AdmissionToken,
) -> QueueDecision | None:
return await _finish_owned_operation(
self._admit_if_current(
incoming,
status_message_id,
parent_reference_id,
admission_token,
),
name=f"messaging-admit-{incoming.message_id}",
)
async def _admit_if_current(
self,
incoming: IncomingMessage,
status_message_id: str,
parent_reference_id: str | None,
admission_token: AdmissionToken,
) -> QueueDecision | None:
"""Commit admission and its exact snapshot as one owned transaction."""
async with self._state_lock:
current_token = AdmissionToken(
stop_generation=self._stop_generation,
clear_generation=self._clear_generations.get(incoming.scope, 0),
)
if admission_token != current_token:
return None
await self.record_outgoing_message(
incoming.platform, incoming.chat_id, status_message_id, "status"
)
decision = await self._tree_queue.admit(
incoming,
status_message_id,
parent_reference_id=parent_reference_id,
)
return decision
def get_tree_count(self) -> int:
return self._tree_queue.get_tree_count()
async def stop_reply(
self,
scope: MessageScope,
reply_id: str,
) -> StopOutcome:
"""Stop the exact voice/tree owner of one replied-to message."""
return await _finish_owned_operation(
self._stop_reply(scope, reply_id),
name=f"messaging-stop-reply-{reply_id}",
)
async def _stop_reply(
self,
scope: MessageScope,
reply_id: str,
) -> StopOutcome:
voice_result = await self._cancel_pending_voice(scope, reply_id)
if voice_result is not None:
self.render_voice_stopped(voice_result)
async with self._state_lock:
node_id = await self._tree_queue.resolve_node_id(scope, reply_id)
if node_id is None:
voices = (voice_result,) if voice_result is not None else ()
return _stop_outcome(voices, CancellationResult())
result = await self._tree_queue.cancel_node(
scope,
node_id,
reason=CancellationReason.STOP,
)
self._apply_cancellation_result(result)
voices = (voice_result,) if voice_result is not None else ()
return _stop_outcome(voices, result)
async def clear_reply(
self,
scope: MessageScope,
reply_id: str,
) -> ReplyClearResult | None:
"""Clear the exact voice/tree owner of one replied-to message."""
return await _finish_owned_operation(
self._clear_reply(scope, reply_id),
name=f"messaging-clear-reply-{reply_id}",
)
async def _clear_reply(
self,
scope: MessageScope,
reply_id: str,
) -> ReplyClearResult | None:
voice_result = await self._cancel_pending_voice(scope, reply_id)
async with self._state_lock:
subtree = await self._tree_queue.remove_message_subtree(
scope,
reply_id,
reason=CancellationReason.CLEAR,
)
if not subtree.tree_matched and voice_result is None:
return None
delete_message_ids = set(subtree.delete_message_ids)
if voice_result is not None:
delete_message_ids.update(voice_result.delete_message_ids)
return ReplyClearResult(
delete_message_ids=frozenset(delete_message_ids),
tree_matched=subtree.tree_matched,
)
async def stop_all_tasks(self) -> StopOutcome:
"""Stop every pending and active messaging task."""
return await _finish_owned_operation(
self._stop_all_tasks(),
name="messaging-stop-all",
)
async def _stop_all_tasks(self) -> StopOutcome:
voice_results = await self._cancel_all_pending_voices()
for voice in voice_results:
self.render_voice_stopped(voice)
async with self._state_lock:
def publish_stop() -> None:
self._stop_generation += 1
logger.info("Cancelling tree queue tasks...")
result = await self._tree_queue.cancel_all(
reason=CancellationReason.STOP, on_committed=publish_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 _stop_outcome(voice_results, result)
async def clear_chat(self, platform: str, chat_id: str) -> frozenset[str]:
"""Clear FCC state atomically with respect to later turn admission."""
return await _finish_owned_operation(
self._clear_chat(platform, chat_id),
name=f"messaging-clear-{platform}-{chat_id}",
)
async def _clear_chat(
self,
platform: str,
chat_id: str,
) -> frozenset[str]:
"""Reset one chat's FCC state and return all tracked deletion IDs."""
clear_scope = MessageScope(platform=platform, chat_id=chat_id)
voice_results = await self._cancel_pending_voices_in_scope(clear_scope)
async with self._state_lock:
delete_message_ids: set[str] = set()
for voice in voice_results:
delete_message_ids.update(voice.delete_message_ids)
delete_message_ids.update(
await self.session_store.get_tracked_message_ids_for_chat(
platform, chat_id
)
)
delete_message_ids.update(
await self._tree_queue.get_message_ids_for_chat(platform, chat_id)
)
def publish_clear() -> None:
self._clear_generations[clear_scope] = (
self._clear_generations.get(clear_scope, 0) + 1
)
await self._tree_queue.clear_scope(
clear_scope, reason=CancellationReason.CLEAR, on_committed=publish_clear
)
return frozenset(delete_message_ids)
async def _cancel_all_pending_voices(
self,
) -> tuple[VoiceCancellationResult, ...]:
cancellation = self.voice_cancellation
if cancellation is None:
return ()
return await cancellation.cancel_all_pending_voices()
async def _cancel_pending_voices_in_scope(
self,
scope: MessageScope,
) -> tuple[VoiceCancellationResult, ...]:
cancellation = self.voice_cancellation
if cancellation is None:
return ()
return await cancellation.cancel_pending_voices_in_scope(scope)
async def _cancel_pending_voice(
self,
scope: MessageScope,
reply_id: str,
) -> VoiceCancellationResult | None:
cancellation = self.voice_cancellation
if cancellation is None:
return None
return await cancellation.cancel_pending_voice(scope, reply_id)
def render_voice_stopped(self, result: VoiceCancellationResult) -> None:
"""Publish terminal UI for a voice cancelled before tree ownership."""
if result.status_message_id is None:
return
self.outbound.fire_and_forget(
self.outbound.queue_edit_message(
result.scope.chat_id,
result.status_message_id,
self.format_status("⏹", "Stopped."),
parse_mode=self._parse_mode(),
)
)
async def forget_tracked_message_ids(
self,
platform: str,
chat_id: str,
message_ids: set[str],
) -> None:
try:
await self.session_store.forget_tracked_message_ids(
platform, chat_id, message_ids
)
except Exception as exc:
logger.warning(
"Failed to update managed-message log after clear: {}",
type(exc).__name__,
)
async def record_outgoing_message(
self,
platform: str,
chat_id: str,
msg_id: str | None,
kind: str,
) -> bool:
"""Record an outgoing message ID for /clear and report ownership."""
if not msg_id:
return False
try:
await self.session_store.record_message_id(
platform,
chat_id,
str(msg_id),
"out",
kind,
)
except Exception as exc:
logger.debug(
"Failed to record message_id: {}",
format_exception_for_log(
exc,
log_full_message=self._log_messaging_error_details,
),
)
return False
return True
async def _record_incoming_message(self, incoming: IncomingMessage) -> bool:
"""Record an inbound prompt, voice note, or command for standalone clear."""
command = parse_command_base(incoming.text)
kind = (
"command"
if command.startswith("/")
else "voice"
if incoming.status_message_id is not None
else "prompt"
)
try:
await self.session_store.record_message_id(
incoming.platform,
incoming.chat_id,
str(incoming.message_id),
"in",
kind,
)
except Exception as exc:
logger.debug(
"Failed to record managed inbound message_id: {}",
format_exception_for_log(
exc,
log_full_message=self._log_messaging_error_details,
),
)
return False
return True
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(
effect.node.scope.chat_id,
effect.node.status_message_id,
self.format_status("⏹", "Stopped."),
parse_mode=self._parse_mode(),
)
)
def _apply_unexpected_failure(self, result: FailureResult) -> None:
"""Render a failure reported by the execution owner."""
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", result.message),
parse_mode=self._parse_mode(),
)
)
__all__ = ["MessagingWorkflow"]