Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Processing indicator lifecycle management.
This module owns the short-lived UI state shown while a user turn is being
processed: acknowledgement messages, acknowledgement reactions, and typing
indicators. Agent implementations should not know platform-specific cleanup
details; they should only ask this service to delete or finish an indicator.
"""
from __future__ import annotations
import asyncio
import copy
import logging
from contextlib import asynccontextmanager
from dataclasses import dataclass, replace
from typing import Any, Optional
from config.platform_registry import PlatformCapabilities, get_platform_descriptor
from modules.im import MessageContext
from vibe.i18n import t as i18n_t
logger = logging.getLogger(__name__)
_PROCESSING_INDICATOR_MODES = ("typing", "reaction", "message")
ACK_REACTION_EMOJI = "👀"
# Shown while an IM message is waiting behind a running turn (blocked on the
# runtime gate). It is promoted to ACK_REACTION_EMOJI when this message's turn
# actually starts. See AgentService.handle_message (show_queued_reaction /
# promote_reaction_to_running).
QUEUED_REACTION_EMOJI = "👌"
# Admission receipts for an IM message that did NOT start its own turn. Without
# them a message sent while a turn is already running gets no feedback at all:
# the message handler hands it to its durable Delivery owner and returns before
# any processing indicator is started, and a steered input never dispatches a
# turn of its own. See MessageHandler._admit_human_delivery.
STEERED_REACTION_EMOJI = "✍️"
UNCONFIRMED_REACTION_EMOJI = "🤔"
NOT_DELIVERED_REACTION_EMOJI = "🤷"
# Terminal receipts that REPLACE the running 👀 instead of clearing it. Plain
# removal is the right ending for a turn that produced its own result — the
# result IS the receipt — but it is ambiguous for a turn that ended without one:
# a stopped turn and a turn whose runtime died both leave a message that simply
# stopped having a reaction, which is also what a healthy silent completion
# looks like. These two say which happened, and they persist on the triggering
# message rather than costing a line in the thread.
STOPPED_REACTION_EMOJI = "⏹️"
INTERRUPTED_REACTION_EMOJI = "⚠️"
# Delivery state -> admission receipt. States that own a turn (``claimed``,
# ``steering``, ``interrupt_waiting``) are absent on purpose: their feedback is
# the turn's own processing indicator, and an ``accepted`` Delivery is only
# reported here when it was steered into a turn already running.
_ADMISSION_ACK_REACTIONS: dict[str, str] = {
"accepted": STEERED_REACTION_EMOJI,
"queued": QUEUED_REACTION_EMOJI,
"pending_steer": QUEUED_REACTION_EMOJI,
"reconciling_steer": UNCONFIRMED_REACTION_EMOJI,
"retired": NOT_DELIVERED_REACTION_EMOJI,
}
# Backstop for receipts nothing ever reads back (a queue drained by a Stop, a
# session archived mid-wait, a terminal ✍️/🤷 on a message no other Delivery
# touches). Bounded FIFO eviction: dropping the oldest key only forfeits a later
# replace/clear, never the reaction itself.
_ADMISSION_ACK_REGISTRY_LIMIT = 1024
# Registry marker for a message whose own turn has started. Kept so a receipt
# still in flight when the turn began cannot decorate it afterwards.
_ADMISSION_ACK_CONSUMED = "\x00turn-started"
# Typing keepalive bounds. "<bot> is typing…" claims a turn is working on this
# conversation right now, so the loop re-checks that claim on every tick instead
# of trusting every exit path to cancel it (see _typing_keepalive_loop).
TYPING_KEEPALIVE_INTERVAL_SECONDS = 5.0
# Backstop only: the per-tick currency check already ends typing when its turn
# ends. Agent turns have no product maximum (they may run for hours and the
# OpenCode active-turn timeout is disabled by default), so this sits at the
# longest default bound Avibe puts on unattended work, the 6 h command-task
# timeout. Hitting it on a real turn only drops the typing hint; the turn, its
# status and its result are unaffected.
TYPING_KEEPALIVE_MAX_SECONDS = 6 * 60 * 60
# A target that rejects this many sends in a row (deleted thread, revoked
# access) will not recover within the turn.
TYPING_KEEPALIVE_MAX_FAILURES = 3
@dataclass
class ProcessingIndicatorHandle:
"""Runtime handle for a processing indicator."""
context: MessageContext
ack_message_id: Optional[str] = None
ack_message_channel_id: Optional[str] = None
ack_reaction_message_id: Optional[str] = None
ack_reaction_emoji: Optional[str] = None
# Captured only by start(), which runs for human turns. Backend-initiated
# turns may reuse a context with an old message_id and must not stamp it.
terminal_reaction_message_id: Optional[str] = None
typing_indicator_active: bool = False
typing_indicator_task: Optional[asyncio.Task] = None
# Ownership of the typing keepalive: whoever starts it finishes it, unless it
# was handed off to the tracked turn. Before track_turn the owner is the task
# that started it; track_turn records the runtime turn it was handed to. Both
# are process-local and deliberately absent from the snapshot.
owner_task: Optional[asyncio.Task] = None
runtime_turn_key: Optional[str] = None
runtime_turn_token: Optional[str] = None
# True when the reaction indicator is the selected mode for this turn. The
# reaction itself is added at the runtime gate (queued 👌 → running 👀), not
# here, so this flag tells the gate hooks whether to act. It is intentionally
# NOT part of to_snapshot/from_snapshot: the only snapshot/restore path
# (OpenCode poll loop) runs AFTER the reaction was already promoted to 👀, and
# finish() keys off ack_reaction_emoji directly, so the flag is not load-bearing
# across a restore.
reaction_indicator_selected: bool = False
@property
def handed_off(self) -> bool:
return bool(self.runtime_turn_token)
def to_snapshot(self) -> dict[str, Any]:
payload = self.context.platform_specific or {}
return {
"platform": self.context.platform or payload.get("platform") or "",
"user_id": self.context.user_id or "",
"channel_id": self.context.channel_id or "",
"thread_id": self.context.thread_id or "",
"message_id": self.context.message_id or "",
"is_dm": bool(payload.get("is_dm", False)),
"context_token": str(payload.get("context_token") or ""),
"ack_message_id": self.ack_message_id,
"ack_message_channel_id": self.ack_message_channel_id,
"ack_reaction_message_id": self.ack_reaction_message_id,
"ack_reaction_emoji": self.ack_reaction_emoji,
"terminal_reaction_message_id": self.terminal_reaction_message_id,
"typing_indicator_active": self.typing_indicator_active,
}
@classmethod
def from_snapshot(cls, data: dict[str, Any]) -> "ProcessingIndicatorHandle":
platform = str(data.get("platform") or "")
context_token = str(data.get("context_token") or "")
platform_specific: dict[str, Any] = {}
if platform:
platform_specific["platform"] = platform
if data.get("is_dm") is not None:
platform_specific["is_dm"] = bool(data.get("is_dm"))
if context_token:
platform_specific["context_token"] = context_token
context = MessageContext(
user_id=str(data.get("user_id") or ""),
channel_id=str(data.get("channel_id") or ""),
platform=platform or None,
thread_id=data.get("thread_id") or None,
message_id=data.get("message_id") or None,
platform_specific=platform_specific or None,
)
return cls(
context=context,
ack_message_id=data.get("ack_message_id") or None,
ack_message_channel_id=data.get("ack_message_channel_id") or data.get("channel_id") or None,
ack_reaction_message_id=data.get("ack_reaction_message_id") or None,
ack_reaction_emoji=data.get("ack_reaction_emoji") or None,
terminal_reaction_message_id=(
data.get("terminal_reaction_message_id")
or data.get("ack_reaction_message_id")
or data.get("message_id")
or None
),
typing_indicator_active=bool(data.get("typing_indicator_active", False)),
)
class ProcessingIndicatorService:
"""Start and finish processing indicators through one owner."""
def __init__(self, controller):
self.controller = controller
self.config = controller.config
self._indicators_by_turn_token: dict[str, Any] = {}
self._admission_acks: dict[str, str] = {}
self._admission_ack_locks: dict[str, asyncio.Lock] = {}
def _get_im_client(self, context: MessageContext):
getter = getattr(self.controller, "get_im_client_for_context", None)
if callable(getter):
return getter(context)
return self.controller.im_client
def _get_context_platform(self, context: MessageContext) -> str:
return (
context.platform
or (context.platform_specific or {}).get("platform")
or getattr(self.config, "platform", "")
)
def _capabilities(self, context: MessageContext) -> PlatformCapabilities:
return get_platform_descriptor(self._get_context_platform(context)).capabilities
def _mode_supported(
self,
capabilities: PlatformCapabilities,
mode: str,
context: MessageContext,
) -> bool:
if mode == "typing":
return capabilities.supports_typing_indicator
if mode == "reaction":
return capabilities.supports_reaction_indicator and bool(self._reaction_target_message_id(context))
if mode == "message":
return capabilities.supports_message_indicator
return False
def _reaction_target_message_id(self, context: MessageContext) -> Optional[str]:
payload = context.platform_specific or {}
if isinstance(payload, dict):
target_id = payload.get("processing_indicator_message_id")
if target_id:
return str(target_id)
return context.message_id
def _candidate_modes(self, capabilities: PlatformCapabilities) -> list[str]:
preferred = capabilities.preferred_processing_indicator
configured = getattr(self.config, "ack_mode", "typing")
if capabilities.force_preferred_processing_indicator:
candidates = [preferred]
else:
candidates = [configured, preferred, "typing", "reaction", "message"]
return [
mode
for index, mode in enumerate(candidates)
if mode in _PROCESSING_INDICATOR_MODES and mode not in candidates[:index]
]
def _concise_status_bubble_active(self, context: MessageContext) -> bool:
check = getattr(self.controller, "uses_concise_status_bubble", None)
if not callable(check):
return False
try:
return bool(check(context))
except Exception:
logger.debug("uses_concise_status_bubble check failed; not suppressing", exc_info=True)
return False
def _processing_modes(self, context: MessageContext) -> list[str]:
capabilities = self._capabilities(context)
return [
mode
for mode in self._candidate_modes(capabilities)
if self._mode_supported(capabilities, mode, context)
]
def target_context(self, context: MessageContext) -> MessageContext:
"""Return the platform-appropriate context for immediate ACK-style replies."""
im_client = self._get_im_client(context)
capabilities = self._capabilities(context)
if capabilities.supports_threads and im_client.should_use_thread_for_reply() and context.thread_id:
return MessageContext(
user_id=context.user_id,
channel_id=context.channel_id,
platform=context.platform,
thread_id=context.thread_id,
message_id=context.message_id,
platform_specific=context.platform_specific,
)
return context
def _get_ack_text(self, agent_name: str) -> str:
label = agent_name or self.controller.agent_service.default_agent
agent_label = label.capitalize() if label else ""
lang = self.controller._get_lang() if hasattr(self.controller, "_get_lang") else getattr(self.config, "language", "en")
return f"📨 {i18n_t('message.ack', lang, agent=agent_label)}"
def _typing_turn_is_current(self, handle: ProcessingIndicatorHandle) -> bool:
"""Whether the turn that owns this typing keepalive is still running.
After hand-off the runtime turn gate is the authority: a released or
superseded gate means the turn is over even if no cleanup reached this
handle (a dropped stale emit, a backend refresh). Before hand-off there is
no gate token yet, so the starting task stands in for the turn.
"""
if handle.runtime_turn_key and handle.runtime_turn_token:
agent_service = getattr(self.controller, "agent_service", None)
is_current = getattr(agent_service, "runtime_turn_is_current", None)
if not callable(is_current):
return True
return bool(is_current(handle.runtime_turn_key, handle.runtime_turn_token))
owner = handle.owner_task
return owner is None or not owner.done()
async def _typing_keepalive_loop(self, handle: ProcessingIndicatorHandle) -> None:
context = handle.context
im_client = self._get_im_client(context)
loop = asyncio.get_running_loop()
deadline = loop.time() + TYPING_KEEPALIVE_MAX_SECONDS
failures = 0
while True:
await asyncio.sleep(TYPING_KEEPALIVE_INTERVAL_SECONDS)
if not self._typing_turn_is_current(handle):
logger.debug("Typing keepalive stopped: turn ended for %s", context.channel_id)
break
if loop.time() >= deadline:
logger.warning(
"Typing keepalive reached its %ss cap for %s channel=%s thread=%s; stopping",
TYPING_KEEPALIVE_MAX_SECONDS,
context.platform or "unknown",
context.channel_id,
context.thread_id,
)
break
try:
ok = bool(await im_client.send_typing_indicator(context))
except Exception as err:
logger.debug("Typing keepalive send failed: %s", err)
ok = False
if ok:
failures = 0
continue
failures += 1
if failures >= TYPING_KEEPALIVE_MAX_FAILURES:
logger.info(
"Typing keepalive stopped after %d failed sends for %s channel=%s thread=%s",
failures,
context.platform or "unknown",
context.channel_id,
context.thread_id,
)
break
if handle.typing_indicator_active and self._should_clear_typing_indicator(handle):
# Platforms whose typing state persists until cancelled would keep
# showing it after the loop stops on its own.
try:
await im_client.clear_typing_indicator(context)
except Exception as err:
logger.debug("Failed to clear typing indicator: %s", err)
def _admission_ack_registry(self) -> dict[str, str]:
registry = getattr(self, "_admission_acks", None)
if not isinstance(registry, dict):
registry = {}
self._admission_acks = registry
return registry
def _remember_admission_ack(self, key: str, value: str) -> None:
registry = self._admission_ack_registry()
registry.pop(key, None)
registry[key] = value
while len(registry) > _ADMISSION_ACK_REGISTRY_LIMIT:
registry.pop(next(iter(registry)), None)
def _admission_ack_locks_registry(self) -> dict[str, list]:
locks = getattr(self, "_admission_ack_locks", None)
if not isinstance(locks, dict):
locks = {}
self._admission_ack_locks = locks
return locks
@asynccontextmanager
async def _admission_ack_guard(self, key: str):
"""Serialize every receipt operation on one message.
Both halves await a platform call, so without this an ``add_reaction``
still in flight would record its emoji *after* the turn's ``start()``
already looked for one to clear, stranding a 👌 next to the running
indicator.
"""
locks = self._admission_ack_locks_registry()
entry = locks.get(key)
if entry is None:
entry = locks[key] = [asyncio.Lock(), 0]
entry[1] += 1
try:
async with entry[0]:
yield
finally:
entry[1] -= 1
if entry[1] <= 0:
locks.pop(key, None)
def _admission_ack_key(self, context: MessageContext) -> Optional[str]:
message_id = self._reaction_target_message_id(context)
if not message_id:
return None
return "|".join(
(
self._get_context_platform(context),
str(context.channel_id or ""),
str(message_id),
)
)
@staticmethod
def _admission_receipt(state: str, admission: str) -> Optional[str]:
"""Resolve one Delivery state into the receipt it should show.
``accepted`` is deliberately gated on explicit steer provenance: an
idempotent re-entry of an already accepted Delivery reports the state
without an ``admission``, and that observation says nothing about
whether the input joined a running turn or started its own.
"""
normalized = str(state or "").strip()
if normalized == "accepted" and admission != "steered":
return None
return _ADMISSION_ACK_REACTIONS.get(normalized)
async def ack_delivery_state(
self,
context: MessageContext,
*,
state: str,
admission: str = "",
) -> Optional[str]:
"""Report the admission outcome of one IM input as a reaction receipt.
Applies only to input that did not start a turn of its own: a started
turn already answers with the normal processing indicator. Returns the
emoji that was applied, or ``None`` when nothing was reported.
"""
if admission == "started":
return None
emoji = self._admission_receipt(state, admission)
if not emoji:
return None
message_id = self._reaction_target_message_id(context)
if not message_id:
return None
capabilities = self._capabilities(context)
if not self._mode_supported(capabilities, "reaction", context):
# Platforms without reactions (e.g. WeChat) stay silent rather than
# posting a bubble per queued message.
return None
key = self._admission_ack_key(context)
if not key:
return None
async with self._admission_ack_guard(key):
registry = self._admission_ack_registry()
previous = registry.get(key)
if previous == _ADMISSION_ACK_CONSUMED:
# This message's own turn already took the message over; a late
# receipt would sit next to (or replace) the running indicator.
return None
if previous == emoji:
return emoji
im_client = self._get_im_client(context)
if previous:
try:
await im_client.remove_reaction(context, message_id, previous)
except Exception as err:
logger.debug("Failed to remove previous admission ack: %s", err)
try:
applied = await im_client.add_reaction(context, message_id, emoji)
except Exception as err:
logger.debug("Failed to add admission ack reaction: %s", err)
applied = False
if not applied:
registry.pop(key, None)
return None
# Every receipt is remembered, terminal ones included. A reaction
# target can be shared — a quick-reply callback reacts on its bot
# echo, so two Deliveries settle on one message — and a platform
# shows one reaction per (message, emoji, bot). The receipt therefore
# describes the message rather than any one Delivery: last writer
# wins, and the previous receipt is removed instead of stacked. The
# FIFO cap bounds what a terminal receipt leaves behind.
self._remember_admission_ack(key, emoji)
return emoji
async def clear_admission_ack(self, context: MessageContext) -> None:
"""Remove the admission receipt once this input's own turn takes over."""
key = self._admission_ack_key(context)
if not key:
return
async with self._admission_ack_guard(key):
registry = self._admission_ack_registry()
emoji = registry.get(key)
# Mark the message as taken over before awaiting the platform call:
# a receipt that arrives late must not re-decorate a running turn.
self._remember_admission_ack(key, _ADMISSION_ACK_CONSUMED)
if not emoji or emoji == _ADMISSION_ACK_CONSUMED:
return
try:
await self._get_im_client(context).remove_reaction(
context,
self._reaction_target_message_id(context),
emoji,
)
except Exception as err:
logger.debug("Failed to remove admission ack reaction: %s", err)
async def clear_merged_admission_acks(self, context: MessageContext) -> None:
"""Clear the receipts of every Delivery merged into this one Turn.
Deliveries without a native message id (quick-reply callbacks) can be
merged into a single Turn, but only the FIRST one hydrates the dispatch
context. The others are accepted as part of that Turn and never
dispatched on their own, so their 👌 would stay up forever unless this
Turn clears their reaction targets too.
"""
payload = context.platform_specific or {}
targets = payload.get("delivery_ack_targets") if isinstance(payload, dict) else None
if not isinstance(targets, (list, tuple)) or not targets:
return
own_target = self._reaction_target_message_id(context)
for target in targets:
target_id = str(target or "").strip()
if not target_id or target_id == own_target:
continue
merged = copy.copy(context)
spec = dict(payload)
spec["processing_indicator_message_id"] = target_id
merged.platform_specific = spec
await self.clear_admission_ack(merged)
async def start(self, context: MessageContext, agent_name: str, *, enabled: bool = True) -> ProcessingIndicatorHandle:
handle = ProcessingIndicatorHandle(
context=context,
terminal_reaction_message_id=self._reaction_target_message_id(context),
)
# A queued input carries an admission receipt (👌) that this turn's own
# indicator now replaces. Platforms that stack reactions would otherwise
# show both, and the receipt would outlive the wait it described.
await self.clear_admission_ack(context)
await self.clear_merged_admission_acks(context)
if not enabled:
return handle
if self._concise_status_bubble_active(context):
# The concise status bubble is the primary progress indicator, but we
# still want the lightweight reaction ack AND typing keepalive (both
# best-effort, both cleaned up on finish). We only drop the ack MESSAGE
# mode — a separate text bubble would duplicate the status bubble and
# can't be deleted on Slack. (B2)
#
# The reaction is SELECTED here but ADDED at the runtime gate so a
# message waiting behind a running turn shows the queued 👌 and only
# flips to 👀 when its turn truly starts (show_queued_reaction /
# promote_reaction_to_running). Typing stays eager for immediate feedback.
capabilities = self._capabilities(context)
if self._mode_supported(capabilities, "reaction", context):
handle.reaction_indicator_selected = True
if self._mode_supported(capabilities, "typing", context):
await self._start_typing_indicator(handle)
return handle
for mode in self._processing_modes(context):
if mode == "message" and await self._start_message_indicator(handle, agent_name):
return handle
if mode == "typing" and await self._start_typing_indicator(handle):
return handle
if mode == "reaction":
# Reaction is the selected mode but is added at the runtime gate
# (queued 👌 → running 👀), not eagerly here. Selecting it preserves
# the single-mode "first match wins" contract: we stop trying lower
# modes just as if the reaction had been applied.
handle.reaction_indicator_selected = True
return handle
return handle
async def _start_message_indicator(self, handle: ProcessingIndicatorHandle, agent_name: str) -> bool:
ack_context = self.target_context(handle.context)
try:
ack_message_id = await self._get_im_client(ack_context).send_message(
ack_context,
self._get_ack_text(agent_name),
)
except Exception as ack_err:
logger.debug("Failed to send ack message: %s", ack_err)
return False
if not ack_message_id:
logger.info("Ack message not applied (platform returned empty message id)")
return False
handle.ack_message_id = ack_message_id
handle.ack_message_channel_id = ack_context.channel_id
return True
async def _start_typing_indicator(self, handle: ProcessingIndicatorHandle) -> bool:
context = handle.context
im_client = self._get_im_client(context)
try:
ok = await im_client.send_typing_indicator(context)
except Exception as ack_err:
logger.debug("Failed to send typing ack: %s", ack_err)
return False
if not ok:
logger.info("Typing indicator not applied (platform returned False)")
return False
handle.typing_indicator_active = True
handle.owner_task = handle.owner_task or asyncio.current_task()
handle.typing_indicator_task = asyncio.create_task(self._typing_keepalive_loop(handle))
return True
async def _start_reaction_indicator(
self,
handle: ProcessingIndicatorHandle,
*,
emoji: str = ACK_REACTION_EMOJI,
) -> bool:
context = handle.context
message_id = self._reaction_target_message_id(context)
if not message_id:
return False
im_client = self._get_im_client(context)
try:
ok = await im_client.add_reaction(context, message_id, emoji)
except Exception as ack_err:
logger.debug("Failed to add reaction ack: %s", ack_err)
return False
if not ok:
logger.info("Ack reaction not applied (platform returned False)")
return False
handle.ack_reaction_message_id = message_id
handle.ack_reaction_emoji = emoji
return True
async def stamp_orphaned_terminal_reaction(
self,
context: MessageContext,
message_id: str,
terminal_emoji: str,
) -> bool:
"""Retire a running 👀 left behind by a runtime that died mid-turn.
The in-memory handle does NOT survive a service restart — only the
OpenCode poll loop snapshots one, and it restores after the promotion to
👀 — so a turn whose process disappeared leaves its running reaction on
the user's message with nothing left to clear it. Recovery recovers the
originating message id from the durable ledger, so it can finish the
lifecycle the dead process could not: drop the stale 👀 and leave the
terminal receipt in its place.
Both halves are best-effort and independent. A platform that already lost
the reaction (message deleted, history trimmed) must still get the
terminal receipt attempted, so the removal failing does not skip it.
"""
if not message_id or not terminal_emoji:
return False
im_client = self._get_im_client(context)
try:
await im_client.remove_reaction(context, message_id, ACK_REACTION_EMOJI)
except Exception as err:
logger.debug("Failed to remove orphaned ack reaction: %s", err)
try:
return bool(await im_client.add_reaction(context, message_id, terminal_emoji))
except Exception as err:
logger.debug("Failed to stamp orphaned terminal reaction: %s", err)
return False
async def _stamp_terminal_reaction_without_indicator(
self,
handle: ProcessingIndicatorHandle,
terminal_emoji: str,
) -> bool:
"""Leave the terminal receipt when the turn's indicator was not a reaction.
There is no 👀 to replace here, so nothing is removed — the receipt is
added to the message that started the turn. Capability-gated and
best-effort: a platform without reactions (WeChat) or without a target
message id simply ends with no receipt, same as before.
"""
context = handle.context
message_id = handle.terminal_reaction_message_id
if not message_id or not self._capabilities(context).supports_reaction_indicator:
return False
try:
return bool(await self._get_im_client(context).add_reaction(context, message_id, terminal_emoji))
except Exception as err:
logger.debug("Failed to add terminal reaction without an indicator: %s", err)
return False
def _resolve_handle(self, request_or_handle: Any) -> tuple[ProcessingIndicatorHandle, Optional[Any]]:
if isinstance(request_or_handle, ProcessingIndicatorHandle):
return request_or_handle, None
request = request_or_handle
return self.handle_from_request(request), request
@staticmethod
def _sync_reaction_to_request(handle: ProcessingIndicatorHandle, request: Optional[Any]) -> None:
# Keep the request's parallel reaction fields in lockstep with the handle.
# handle_from_request prefers the live handle object, but the OpenCode poll
# snapshot path reads request.ack_reaction_* directly, so they must not drift.
if request is not None:
request.ack_reaction_message_id = handle.ack_reaction_message_id
request.ack_reaction_emoji = handle.ack_reaction_emoji
async def show_queued_reaction(self, request_or_handle: Any) -> bool:
"""Add the queued 👌 reaction for a message waiting behind a running turn.
Acts only when the reaction indicator is the selected mode for this turn and
no reaction is shown yet. Returns True only when 👌 was actually applied, so
the caller knows it must be cleaned up if the queued message is cancelled
before it ever runs.
"""
handle, request = self._resolve_handle(request_or_handle)
if not handle.reaction_indicator_selected:
return False
if handle.ack_reaction_emoji:
return False
applied = await self._start_reaction_indicator(handle, emoji=QUEUED_REACTION_EMOJI)
if applied:
self._sync_reaction_to_request(handle, request)
return applied
async def promote_reaction_to_running(self, request_or_handle: Any, *, agent_name: Optional[str] = None) -> None:
"""Switch the reaction to the running 👀 when this turn actually starts.
queued 👌 shown -> remove 👌 then add 👀; nothing shown yet (non-busy fast
path) -> add 👀; already 👀 -> no-op (idempotent). No-op when the reaction
indicator is not the selected mode. If the 👀 add fails at runtime, fall back
through the remaining indicator modes (``agent_name`` labels the ack message).
"""
handle, request = self._resolve_handle(request_or_handle)
if not handle.reaction_indicator_selected:
return
if handle.ack_reaction_emoji == ACK_REACTION_EMOJI:
return
if handle.ack_reaction_emoji == QUEUED_REACTION_EMOJI and handle.ack_reaction_message_id:
removed = False
try:
removed = bool(
await self._get_im_client(handle.context).remove_reaction(
handle.context,
handle.ack_reaction_message_id,
handle.ack_reaction_emoji,
)
)
except Exception as err:
logger.debug("Failed to remove queued reaction on promote: %s", err)
if not removed:
# The queued 👌 is still on the message. Keep owning it on the handle
# (do NOT clear the fields and do NOT stack 👀 on top) so finish() can
# still remove it on the terminal result. Better a stale 👌 that gets
# cleaned up than a leaked one or two reactions at once.
return
handle.ack_reaction_message_id = None
handle.ack_reaction_emoji = None
applied = await self._start_reaction_indicator(handle, emoji=ACK_REACTION_EMOJI)
if not applied and not handle.typing_indicator_active and not handle.ack_message_id:
# The reaction add failed at runtime (e.g. missing reactions scope or a
# transient API error). Because start() deferred the reaction, the normal
# mode loop never tried a lower candidate — fall through the remaining
# modes here so the user still gets a processing ack instead of none (P2):
# typing first when supported, else the ack message (e.g. Lark/Feishu
# support reactions + message but NOT typing). Best-effort, capability-gated.
capabilities = self._capabilities(handle.context)
fell_back = False
if self._mode_supported(capabilities, "typing", handle.context):
fell_back = await self._start_typing_indicator(handle)
if not fell_back and self._mode_supported(capabilities, "message", handle.context):
fell_back = await self._start_message_indicator(handle, agent_name or "")
if fell_back:
self._warn_ack_mode_downgraded(
handle.context,
"typing" if handle.typing_indicator_active else "message",
)
self._sync_reaction_to_request(handle, request)
def _warn_ack_mode_downgraded(self, context: MessageContext, applied_mode: str) -> None:
"""Report that the configured ack mode failed and a lower one was used.
The fallback ladder is deliberately silent about *which* mode won, so a
user who picked ``reaction`` and keeps seeing an ack message has nothing
to go on. Warn once per downgraded turn, naming the channel — a DM whose
channel_id is a user id is the usual cause.
"""
configured = str(getattr(self.config, "ack_mode", "typing") or "typing")
if configured != "reaction":
return
logger.warning(
"Ack mode 'reaction' failed for %s channel=%s; downgraded to '%s'. "
"Check that the bot can react in this conversation (reactions:write, membership, "
"and a real channel id — a DM context must not carry the user id).",
context.platform or "unknown",
context.channel_id,
applied_mode,
)
@staticmethod
def _turn_tokens(context: MessageContext) -> set[str]:
payload = context.platform_specific or {}
tokens = set()
for key in ("turn_token", "agent_runtime_turn_token"):
token = str(payload.get(key) or "").strip()
if token:
tokens.add(token)
return tokens
def track_turn(self, context: MessageContext, request_or_handle: Any) -> None:
"""Remember this turn's indicator for terminal-result cleanup.
Backends still clean up explicitly with their request object. This registry
is the outbound terminal fallback: a result emit can recover the original
handle by turn token even when a backend terminal branch lost the request.
This is also the hand-off: from here the runtime turn, not the task that
started the indicator, owns its cleanup, and the typing keepalive follows
that turn's gate.
"""
handle = request_or_handle
if not isinstance(handle, ProcessingIndicatorHandle):
handle = getattr(request_or_handle, "processing_indicator", None)
payload = context.platform_specific or {}
runtime_key = str(payload.get("agent_runtime_turn_key") or "").strip()
runtime_token = str(payload.get("agent_runtime_turn_token") or "").strip()
if isinstance(handle, ProcessingIndicatorHandle) and runtime_key and runtime_token:
handle.runtime_turn_key = runtime_key
handle.runtime_turn_token = runtime_token
for token in self._turn_tokens(context):
self._indicators_by_turn_token[token] = request_or_handle
def _forget_turn(self, context: MessageContext, handle: ProcessingIndicatorHandle) -> None:
for token in self._turn_tokens(context):
tracked = self._indicators_by_turn_token.get(token)
if tracked is handle or getattr(tracked, "processing_indicator", None) is handle:
self._indicators_by_turn_token.pop(token, None)
async def finish_terminal_turn(self, context: MessageContext) -> None:
"""Finish the processing indicator for a terminal result emit."""
for token in self._turn_tokens(context):
tracked = self._indicators_by_turn_token.pop(token, None)
if tracked is not None:
await self.finish(tracked)
return
def _delete_context(self, handle: ProcessingIndicatorHandle, channel_id: Optional[str]) -> MessageContext:
target_channel_id = channel_id or handle.ack_message_channel_id
if target_channel_id and target_channel_id != handle.context.channel_id:
return replace(handle.context, channel_id=target_channel_id)
return handle.context
def _should_delete_ack_message(self, handle: ProcessingIndicatorHandle) -> bool:
return self._capabilities(handle.context).supports_message_indicator_delete
def _should_clear_typing_indicator(self, handle: ProcessingIndicatorHandle) -> bool:
return self._capabilities(handle.context).typing_indicator_requires_clear
async def _delete_ack_message_for_handle(
self,
handle: ProcessingIndicatorHandle,
*,
request: Optional[Any] = None,
channel_id: Optional[str] = None,
) -> None:
ack_id = handle.ack_message_id
if not ack_id:
return
if self._should_delete_ack_message(handle):
im_client = self._get_im_client(handle.context)
if hasattr(im_client, "delete_message"):
try:
await im_client.delete_message(self._delete_context(handle, channel_id), ack_id)
except Exception as err:
logger.debug("Could not delete ack message: %s", err)
handle.ack_message_id = None
if request is not None:
request.ack_message_id = None
def apply_to_request(self, request: Any, handle: ProcessingIndicatorHandle) -> None:
request.processing_indicator = handle
request.ack_message_id = handle.ack_message_id
request.ack_reaction_message_id = handle.ack_reaction_message_id
request.ack_reaction_emoji = handle.ack_reaction_emoji
request.terminal_reaction_message_id = handle.terminal_reaction_message_id
request.typing_indicator_active = handle.typing_indicator_active
request.typing_indicator_task = handle.typing_indicator_task
def handle_from_request(self, request: Any) -> ProcessingIndicatorHandle:
handle = getattr(request, "processing_indicator", None)
if isinstance(handle, ProcessingIndicatorHandle):
handle.ack_message_id = handle.ack_message_id or getattr(request, "ack_message_id", None)
handle.ack_reaction_message_id = handle.ack_reaction_message_id or getattr(
request,
"ack_reaction_message_id",
None,
)
handle.ack_reaction_emoji = handle.ack_reaction_emoji or getattr(request, "ack_reaction_emoji", None)
handle.terminal_reaction_message_id = handle.terminal_reaction_message_id or getattr(
request,
"terminal_reaction_message_id",
None,
)
handle.typing_indicator_active = handle.typing_indicator_active or bool(
getattr(request, "typing_indicator_active", False)
)
handle.typing_indicator_task = handle.typing_indicator_task or getattr(request, "typing_indicator_task", None)
return handle
return ProcessingIndicatorHandle(
context=request.context,
ack_message_id=getattr(request, "ack_message_id", None),
ack_message_channel_id=getattr(request.context, "channel_id", None),
ack_reaction_message_id=getattr(request, "ack_reaction_message_id", None),
ack_reaction_emoji=getattr(request, "ack_reaction_emoji", None),
terminal_reaction_message_id=getattr(request, "terminal_reaction_message_id", None),
typing_indicator_active=bool(getattr(request, "typing_indicator_active", False)),
typing_indicator_task=getattr(request, "typing_indicator_task", None),
)
def handle_from_snapshot(self, data: dict[str, Any]) -> ProcessingIndicatorHandle:
return ProcessingIndicatorHandle.from_snapshot(data)
def snapshot_request(self, request: Any) -> dict[str, Any]:
return self.handle_from_request(request).to_snapshot()
async def delete_ack_message(self, request: Any, *, channel_id: Optional[str] = None) -> None:
handle = self.handle_from_request(request)
await self._delete_ack_message_for_handle(handle, request=request, channel_id=channel_id)
if getattr(request, "processing_indicator", None) is None:
request.processing_indicator = handle
def _stale_running_reaction_target(self, handle: ProcessingIndicatorHandle) -> Optional[str]:
"""The message a restart rerun's dead process may have left its 👀 on, unless the
handle owns that reaction itself (its own end retires it then)."""
if (handle.context.platform_specific or {}).get("vibey_resume") is not True:
return None
if not self._capabilities(handle.context).supports_reaction_indicator:
return None
target = self._reaction_target_message_id(handle.context)
if not target or (target == handle.ack_reaction_message_id and handle.ack_reaction_emoji == ACK_REACTION_EMOJI):
return None
return target
async def finish(
self,
request_or_handle: Any,
*,
terminal_emoji: Optional[str] = None,
) -> None:
"""Clear the turn's indicator, optionally leaving a terminal receipt.
``terminal_emoji`` replaces the running 👀 rather than clearing it, for
the endings that produce no result of their own (see
``STOPPED_REACTION_EMOJI`` / ``INTERRUPTED_REACTION_EMOJI``). Omitting it
keeps the historical behavior — a turn that emitted a result needs no
second receipt. Adding the replacement is best-effort: the removal is
what the handle's bookkeeping is keyed on, so a platform that rejects the
new emoji still ends with a cleanly cleared indicator.
"""
if isinstance(request_or_handle, ProcessingIndicatorHandle):
handle = request_or_handle
request = None
else:
request = request_or_handle
handle = self.handle_from_request(request)
# Stop typing before any cleanup call that can hang on the network.
typing_task = handle.typing_indicator_task
if typing_task is not None:
typing_task.cancel()
try:
await typing_task
except asyncio.CancelledError:
pass
except Exception:
logger.debug("Failed to stop typing keepalive task", exc_info=True)
finally:
handle.typing_indicator_task = None
if request is not None:
request.typing_indicator_task = None
await self._delete_ack_message_for_handle(handle, request=request)
if handle.typing_indicator_active and self._should_clear_typing_indicator(handle):
try:
await self._get_im_client(handle.context).clear_typing_indicator(handle.context)
except Exception as err:
logger.debug("Failed to clear typing indicator: %s", err)
if handle.typing_indicator_active:
handle.typing_indicator_active = False
if request is not None:
request.typing_indicator_active = False
stale_target = self._stale_running_reaction_target(handle)
if stale_target:
# A Turn rerun after a restart answers a message that may still wear the 👀 its
# dead process added; this Turn's end retires it too, whatever its own
# indicator. There may be none, so a failed removal decides nothing below.
try:
await self._get_im_client(handle.context).remove_reaction(
handle.context, stale_target, ACK_REACTION_EMOJI
)
except Exception as err:
logger.debug("Failed to remove a rerun's stale running reaction: %s", err)
if terminal_emoji and not handle.ack_reaction_emoji:
# The receipt is not a *reaction* feature, it is the only trace a
# silent ending leaves. ack_mode defaults to 'typing' on every
# platform that has it, so gating the stamp on "the indicator
# happened to be a reaction" would make ⏹️/⚠️ invisible for the
# default configuration — exactly the turns that emit no result.
# Stamp on the originating message instead, wherever reactions work.
await self._stamp_terminal_reaction_without_indicator(handle, terminal_emoji)
if handle.ack_reaction_message_id and handle.ack_reaction_emoji:
reaction_message_id = handle.ack_reaction_message_id
removed = False
try:
removed = bool(
await self._get_im_client(handle.context).remove_reaction(
handle.context,
handle.ack_reaction_message_id,
handle.ack_reaction_emoji,
)
)
except Exception as err:
logger.debug("Failed to remove reaction ack: %s", err)
else:
# Adapters report a failed removal by RETURNING False (Slack,
# Discord, Telegram, Feishu) as often as by raising, and
# ``promote_reaction_to_running`` already treats that value as
# authoritative. Stamping on an unremoved 👀 would leave the
# message showing running AND stopped at once, so the receipt is
# owed only to a removal that actually happened.
if terminal_emoji and removed:
try:
await self._get_im_client(handle.context).add_reaction(
handle.context,
reaction_message_id,
terminal_emoji,
)
except Exception as err:
logger.debug("Failed to add terminal reaction: %s", err)
finally:
handle.ack_reaction_message_id = None
handle.ack_reaction_emoji = None
if request is not None:
request.ack_reaction_message_id = None
request.ack_reaction_emoji = None
if request is not None and getattr(request, "processing_indicator", None) is None:
request.processing_indicator = handle
self._forget_turn(handle.context, handle)