"""Deterministic policy for same-gateway hosted-room Discussions. Pure (no I/O, transport or model knowledge): a frozen local roster plus the complete typed room log yields at most one next driver task. Discussion coordinates live in deterministic ``TaskIdentity`` values and typed terminal events rather than a widened driver payload, so a restart reconstructs tasks from durable state. Callers must reconcile terminal driver rows into publication plans before asking for the next task. """ from __future__ import annotations import hashlib import re from collections.abc import Iterable, Mapping, Sequence from dataclasses import asdict, dataclass from functools import partial from typing import Any, Literal from agent.prompt_builder import CONTROL_FRAME_OPENERS from gateway import hosted_room_driver as driver from gateway import hosted_room_lead as lead_routing from gateway import hosted_room_router as router from gateway import hosted_rooms from gateway import hosted_rooms_common as common from gateway.hosted_room_context import scheduled_post_kind, validate_context from gateway.hosted_room_task_input import validate_task_input from gateway.hosted_rooms_common import compact_json MAX_DISCUSSION_MEMBERS = 6 MIN_DISCUSSION_MEMBERS = 2 MAX_DISCUSSION_ROUNDS = 3 MAX_DISCUSSION_MESSAGES = 10 MAX_DISCUSSION_DELTA_LINES = 24 MAX_USER_TEXT_BYTES = 64 * 1024 MAX_MEMBER_TEXT_BYTES = 64 * 1024 _TRUNCATED_REPLY_NOTICE = "\n\n[Reply truncated. Ask the Bot to share the full result as a file.]" Payload = Mapping[str, Any] DecisionStatus = Literal["idle", "task", "settled", "bounded", "route"] TerminalKind = Literal["settled", "failed", "cancelled", "deferred"] _MENTION_RE = re.compile(r"@([A-Za-z0-9][A-Za-z0-9._:-]*)", re.IGNORECASE) # Openers of Hermes' own control frames (agent.prompt_builder.CONTROL_FRAME_OPENERS: the steer marker, the # compaction handoff, runtime/system notes, background-process and prior-context frames). A member reply is # republished to every peer inside a role=user prompt, so a reply reproducing one of these reads as harness # input to the peers; the opener is relabelled visibly (the words stay, the exact trusted shape does not). # Genuine user lines are never touched. Keep in sync with apps/desktop hermes-bots/group-round-prompt.ts. _MEMBER_CONTROL_FRAME_RE = re.compile( r"\[(?=" + "|".join(opener.replace("]", r"\]") for opener in CONTROL_FRAME_OPENERS) + ")", re.IGNORECASE, ) _MEMBER_CONTROL_FRAME_RELABEL = "[member-quoted " _TURN_ID_RE = re.compile( r"^d(?P[1-9][0-9]*)\.r(?P0|[1-9][0-9]*)\." r"p(?P[0-5])\.s(?P[1-9][0-9]*)\." r"m(?P[0-9a-f]{24})$") def turn_round(turn_id: str) -> int | None: """The 0-based round a Discussion turn id names, or None for a turn id of another shape.""" match = _TURN_ID_RE.fullmatch(turn_id) return int(match.group("round")) if match else None _TARGET_FIELDS = { "local": frozenset({"kind", "profile"}), "peer": frozenset({"kind", "peer_id", "installation_id", "profile", "capability_digest"})} _REMOTE_MEMBER_FIELDS = frozenset({ "connectionId", "connectionKind", "connectionLabel", "connection_id", "connection_kind", "connection_label", "remoteSource", "route", "sourceMissing", "sourceReachable", "sourceScoped", "targetProfile", "target_profile"}) _USER_PAYLOAD_FIELDS = frozenset({"text", "thread_id"}) _TURN_COORDINATE_FIELDS = frozenset( {"discussion_event_id", "member_id", "member_index", "round_index", "task_id", "thread_id", "turn_id", }) _MEMBER_MESSAGE_FIELDS = _TURN_COORDINATE_FIELDS | {"text"} _TERMINAL_FIELDS = { # kind -> exact payload fields (coordinates + seen_through_seq + per-kind extras) kind: _TURN_COORDINATE_FIELDS | {"seen_through_seq", *extra} for kind, extra in ( ("turn.settled", ("message_event_id", "passed")), ("turn.failed", ("error",)), ("turn.cancelled", ("reason",)), ("turn.deferred", ("execution_generation", "reason")))} _TERMINAL_OPTIONAL_FIELDS = {"turn.failed": frozenset({"reason_code"})} _TERMINAL_EVENT_KINDS = frozenset(_TERMINAL_FIELDS) # Gateway-authored control events: kind -> (exact payload fields, identifier fields). _GATEWAY_EVENT_FIELDS = { "room.activity": ( frozenset({"status", "reason_code", "thread_id", "discussion_event_id"}), ("reason_code", "thread_id", "discussion_event_id")), "room.stop_requested": (frozenset({"cancel_id"}), ("cancel_id",))} _EPOCH_STAMPED_KINDS = _TERMINAL_EVENT_KINDS | { "message.member", lead_routing.ASSIGNMENT_EVENT_KIND, router.ROUTED_EVENT_KIND, router.CONTINUED_EVENT_KIND, *_GATEWAY_EVENT_FIELDS} class DiscussionPolicyError(ValueError): """Base class for invalid policy input or unreconstructable state.""" class DiscussionValidationError(DiscussionPolicyError): """Raised when a room, roster, payload, or typed event is malformed.""" class DiscussionReconstructionError(DiscussionPolicyError): """Raised when a persisted task cannot be reproduced from durable state.""" @dataclass(frozen=True) class DiscussionLimits: """Finite per-user-send scheduling ceilings, separate from replay validation.""" max_rounds: int = MAX_DISCUSSION_ROUNDS max_messages: int = MAX_DISCUSSION_MESSAGES def __post_init__(self) -> None: _positive_int(self.max_rounds, label="hosted_rooms.discussion.max_rounds") _positive_int(self.max_messages, label="hosted_rooms.discussion.max_messages") @dataclass(frozen=True) class DiscussionMember: """One immutable local or peer member of the hosted room.""" member_id: str profile: str handle: str display_name: str = "" target: Mapping[str, Any] | None = None @dataclass(frozen=True) class DiscussionRoom: """Validated policy projection of one active hosted room.""" room_id: str name: str members: tuple[DiscussionMember, ...] gateway_id: str authority_epoch: int @dataclass(frozen=True) class DiscussionTaskPlan: """One deterministic member turn compatible with the driver schema.""" identity: driver.TaskIdentity payload: Mapping[str, Any] discussion_event_id: str member: DiscussionMember member_index: int round_index: int seen_through_seq: int @dataclass(frozen=True) class DiscussionDecision: """Current result of replaying one room's Discussion policy.""" status: DecisionStatus reason: str discussion_event_id: str | None = None source_event_seq: int | None = None thread_id: str | None = None task: DiscussionTaskPlan | None = None #: How many times the user granted this discussion another budget (``room.continued``). continues: int = 0 @dataclass(frozen=True) class EventPlan: """One idempotent append for :func:`gateway.hosted_rooms.append_event`.""" event_id: str kind: str actor: Mapping[str, str] payload: Mapping[str, Any] authority_gateway_id: str authority_epoch: int def append_kwargs(self, room_id: str) -> dict[str, Any]: """Return keyword arguments accepted by ``append_event`` (field order matches the dataclass).""" return {"room_id": room_id, **asdict(self)} @dataclass(frozen=True) class PublicationPlan: """Ordered visible and terminal effects for one driver task.""" task_id: str terminal_kind: str events: tuple[EventPlan, ...] @dataclass(frozen=True) class _ValidatedEvent: raw: Payload seq: int event_id: str kind: str actor: Payload payload: Payload _identifier = partial(common.identifier, error=DiscussionValidationError, max_chars=driver.MAX_IDENTIFIER_CHARS) _exact_fields = partial(common.exact_fields, error=DiscussionValidationError) _bounded_int = partial(common.bounded_int, error=DiscussionValidationError) _text = partial(common.text, error=DiscussionValidationError) def _positive_int(value: Any, *, label: str) -> int: return _bounded_int(value, message=f"{label} must be a positive integer", low=1) def _zero_based_int(value: Any, *, label: str, maximum: int) -> int: return _bounded_int(value, message=f"{label} must be an integer between 0 and {maximum}", high=maximum) def _peer_id(member: DiscussionMember) -> str | None: target = member.target return target.get("peer_id") if target and target.get("kind") == "peer" else None def _member_actor(member: DiscussionMember, *, display_name: bool = True) -> dict[str, Any]: """Member actor for the room log; ``connection_id`` (and ``display_name``) only when present.""" actor = {"kind": "member", "id": member.member_id, "profile": member.profile} if (peer_id := _peer_id(member)) is not None: actor["connection_id"] = peer_id if display_name and member.display_name: actor["display_name"] = member.display_name return actor def _all_failure_reasons() -> frozenset[str]: from tools.bot_failure_reasons import ALL_REASONS return ALL_REASONS def validate_user_payload(value: Any) -> dict[str, Any]: """Validate and normalize the exact ``message.user`` Discussion payload.""" payload = _exact_fields(value, label="user payload", required=_USER_PAYLOAD_FIELDS, optional={"attachments"}) normalized: dict[str, Any] = {"thread_id": _identifier(payload["thread_id"], label="thread_id")} if "attachments" in payload: normalized["attachments"] = _message_manifest(payload["attachments"]) text = payload["text"] if not isinstance(text, str) or len(text.encode("utf-8")) > MAX_USER_TEXT_BYTES: raise DiscussionValidationError("user payload text must be a bounded string") if not text.strip() and not normalized.get("attachments"): raise DiscussionValidationError("user payload must contain text or attachments") normalized["text"] = text.strip() return normalized def _message_manifest(value: Any) -> list[dict[str, Any]]: from gateway.hosted_room_attachments import validate_manifest try: return validate_manifest(value) except ValueError as exc: raise DiscussionValidationError(str(exc)) from exc def _validate_member_target(value: Any, *, profile: str, known_profiles: set[str], index: int) -> dict[str, Any]: if value is None: if profile not in known_profiles: raise DiscussionValidationError(f"member {index} profile '{profile}' is not local to this gateway") return {"kind": "local", "profile": profile} if not isinstance(value, Mapping): raise DiscussionValidationError(f"member {index} target must be an object") kind = value.get("kind") if kind not in _TARGET_FIELDS: raise DiscussionValidationError(f"member {index} target kind must be local or peer") target = _exact_fields(value, label=f"member {index} {kind} target", required=_TARGET_FIELDS[kind]) target_profile = _identifier(target["profile"], label=f"member {index} target profile") if kind == "local": if target_profile != profile: raise DiscussionValidationError(f"member {index} local target profile does not match member profile") if profile not in known_profiles: raise DiscussionValidationError(f"member {index} profile '{profile}' is not local to this gateway") return {"kind": "local", "profile": profile} if target_profile != profile: raise DiscussionValidationError(f"member {index} peer target profile does not match member profile") digest = target["capability_digest"] if not isinstance(digest, str) or not re.fullmatch(r"[0-9a-f]{64}", digest): raise DiscussionValidationError(f"member {index} capability_digest must be a sha256 digest") return { "kind": "peer", "peer_id": _identifier(target["peer_id"], label=f"member {index} peer_id"), "installation_id": _identifier(target["installation_id"], label=f"member {index} installation_id"), "profile": target_profile, "capability_digest": digest} def _validate_member(raw: Any, index: int, known_profiles: set[str]) -> DiscussionMember: if not isinstance(raw, Mapping): raise DiscussionValidationError(f"member {index} must be an object") if remote_fields := frozenset(raw) & _REMOTE_MEMBER_FIELDS: raise DiscussionValidationError( f"member {index} contains cross-gateway fields: {', '.join(sorted(remote_fields))}") member = _exact_fields( raw, label=f"member {index}", required=frozenset({"member_id", "profile", "handle"}), optional=frozenset({"display_name", "target"})) member_id, profile, handle = ( _identifier(member[field], label=f"member {index} {label}") for field, label in (("member_id", "id"), ("profile", "profile"), ("handle", "handle"))) target = _validate_member_target(member.get("target"), profile=profile, known_profiles=known_profiles, index=index) if not isinstance(display_name := member.get("display_name", ""), str): raise DiscussionValidationError(f"member {index} display_name must be a string") if len(display_name := display_name.strip()) > hosted_rooms.MAX_ACTOR_LABEL_CHARS: raise DiscussionValidationError(f"member {index} display_name is too long") return DiscussionMember(member_id, profile, handle, display_name, target) def validate_roster(value: Any, *, local_profiles: Iterable[str]) -> tuple[DiscussionMember, ...]: """Validate a frozen 2-6 member roster of profiles on this gateway.""" if not isinstance(value, list): raise DiscussionValidationError("members must be a list") if not MIN_DISCUSSION_MEMBERS <= len(value) <= MAX_DISCUSSION_MEMBERS: raise DiscussionValidationError( f"members must contain between {MIN_DISCUSSION_MEMBERS} and {MAX_DISCUSSION_MEMBERS} entries") known_profiles = {_identifier(profile, label="local profile") for profile in local_profiles} members: list[DiscussionMember] = [] targets: set[str] = set() handles: set[str] = {"all", "everyone"} # reserved mention handles member_ids: set[str] = set() for index, raw in enumerate(value): member = _validate_member(raw, index, known_profiles) unique = "profiles" if member.target.get("kind") == "local" else "targets" for key, seen, message in ( (compact_json(member.target, ensure_ascii=False).casefold(), targets, f"member {unique} must be unique"), (member.handle.casefold(), handles, "member handles must be unique and cannot reserve @all or @everyone"), (member.member_id.casefold(), member_ids, "member ids must be unique")): if key in seen: raise DiscussionValidationError(message) seen.add(key) members.append(member) return tuple(members) def validate_room(value: Any, *, local_profiles: Iterable[str]) -> DiscussionRoom: """Project a hosted-room row into the strict same-gateway policy shape.""" if not isinstance(value, Mapping): raise DiscussionValidationError("room must be an object") if value.get("disbanded_at") is not None: raise DiscussionValidationError("room is disbanded") room_id = _identifier(value.get("room_id"), label="room_id") if not isinstance(name := value.get("name"), str) or not name.strip(): raise DiscussionValidationError("room name must be a non-empty string") if len(name := name.strip()) > hosted_rooms.MAX_ROOM_NAME_CHARS: raise DiscussionValidationError("room name is too long") gateway_id = _identifier(value.get("authority_gateway_id"), label="authority_gateway_id") authority_epoch = _positive_int(value.get("authority_epoch"), label="authority_epoch") members = validate_roster(value.get("members"), local_profiles=local_profiles) return DiscussionRoom(room_id, name, members, gateway_id, authority_epoch) def is_pass_text(value: Any) -> bool: """Return whether a settled member result is Discussion silence.""" text = str(value or "").strip() return not text or re.fullmatch(r"\(?\s*pass\s*\)?\.?", text, re.IGNORECASE) is not None def resolve_mentions( texts: Iterable[str], members: Sequence[DiscussionMember], *, default_all: bool = True ) -> tuple[DiscussionMember, ...]: """Resolve member handles deterministically against the frozen roster.""" by_handle = {member.handle.casefold(): member for member in members} mentioned: set[str] = set() everyone = False for text in texts: for match in _MENTION_RE.finditer(str(text or "")): handle = match.group(1).casefold() if handle in {"all", "everyone"}: everyone = True elif handle in by_handle: mentioned.add(handle) if everyone or (default_all and not mentioned): return tuple(members) return tuple(member for member in members if member.handle.casefold() in mentioned) def _unaddressed_member_mentions( messages: Sequence[_ValidatedEvent], room: DiscussionRoom) -> tuple[DiscussionMember, ...]: """Return peers explicitly cited by a Bot and not heard from afterward.""" cited_at: dict[str, int] = {} last_post_at: dict[str, int] = {} for event in messages: if event.kind != "message.member": continue speaker_id = str(event.payload["member_id"]) last_post_at[speaker_id] = event.seq for member in resolve_mentions((str(event.payload["text"]),), room.members, default_all=False): if member.member_id != speaker_id: cited_at[member.member_id] = event.seq return tuple( member for member in room.members if member.member_id in cited_at and last_post_at.get(member.member_id, 0) <= cited_at[member.member_id]) def _require_gateway_actor(actor: Mapping[str, Any], room: DiscussionRoom, message: str) -> None: if actor.get("kind") != "gateway" or actor.get("id") != room.gateway_id: raise DiscussionValidationError(message) def _member_by_id(room: DiscussionRoom, member_id: Any) -> DiscussionMember: normalized = _identifier(member_id, label="member_id") if (member := next((m for m in room.members if m.member_id == normalized), None)) is None: raise DiscussionValidationError(f"unknown Discussion member '{normalized}'") return member def _validate_turn_coordinates(payload: Mapping[str, Any], room: DiscussionRoom) -> None: _member_by_id(room, payload.get("member_id")) _zero_based_int(payload.get("member_index"), label="member_index", maximum=MAX_DISCUSSION_MEMBERS - 1) # Lowering the scheduling budget must not invalidate already-published higher rounds. _bounded_int(payload.get("round_index"), message="round_index must be a non-negative integer") for field in ("thread_id", "task_id", "turn_id", "discussion_event_id"): _identifier(payload.get(field), label=field) # -- per-kind event payload validators (dispatched by _validate_event) --------- # Each takes (kind, payload, actor, room) and returns the payload to record. def _validate_user_event(kind: str, payload: Payload, actor: Payload, room: DiscussionRoom) -> Payload: payload = validate_user_payload(payload) if actor.get("kind") != "user": raise DiscussionValidationError("message.user requires a user actor") return payload def _validate_member_message(kind: str, payload: Payload, actor: Payload, room: DiscussionRoom) -> Payload: _exact_fields(payload, label="message.member payload", required=_MEMBER_MESSAGE_FIELDS, optional={"attachments", "recipient_member_ids"}) payload = dict(payload) if "attachments" in payload: payload["attachments"] = _message_manifest(payload["attachments"]) if "recipient_member_ids" in payload: recipients = payload["recipient_member_ids"] if not isinstance(recipients, list) or not recipients: raise DiscussionValidationError("recipient_member_ids must be a non-empty list") recipients = [_member_by_id(room, recipient).member_id for recipient in recipients] if len(set(recipients)) != len(recipients): raise DiscussionValidationError("recipient_member_ids must be unique") payload["recipient_member_ids"] = recipients _validate_turn_coordinates(payload, room) if not isinstance(text := payload.get("text"), str) or not text.strip() or is_pass_text(text): raise DiscussionValidationError("message.member text must be a non-pass string") member = _member_by_id(room, payload.get("member_id")) expected = {**_member_actor(member, display_name=False), "connection_id": _peer_id(member)} if any(actor.get(key) != value for key, value in expected.items()): raise DiscussionValidationError("message.member actor does not match roster") return payload def _validate_terminal_event(kind: str, payload: Payload, actor: Payload, room: DiscussionRoom) -> Payload: _exact_fields( payload, label=f"{kind} payload", required=_TERMINAL_FIELDS[kind], optional=_TERMINAL_OPTIONAL_FIELDS.get(kind, frozenset())) _validate_turn_coordinates(payload, room) _positive_int(payload.get("seen_through_seq"), label="seen_through_seq") if actor.get("connection_id") is not None: raise DiscussionValidationError(f"{kind} requires a gateway actor") _require_gateway_actor(actor, room, f"{kind} requires a gateway actor") if kind == "turn.settled": if not isinstance(payload.get("passed"), bool): raise DiscussionValidationError("turn.settled passed must be a boolean") message_event_id = payload.get("message_event_id") if not payload["passed"]: _identifier(message_event_id, label="message_event_id") elif message_event_id is not None: raise DiscussionValidationError("a passed turn cannot reference a member message") return payload field = "error" if kind == "turn.failed" else "reason" if not isinstance(payload.get(field), str) or not payload[field].strip(): raise DiscussionValidationError(f"{kind} {field} must be non-empty") if kind == "turn.deferred": _positive_int(payload.get("execution_generation"), label="execution_generation") if kind == "turn.failed" and "reason_code" in payload and payload["reason_code"] not in _all_failure_reasons(): raise DiscussionValidationError("turn.failed reason_code must use the shared failure vocabulary") return payload def _validate_gateway_event(kind: str, payload: Payload, actor: Payload, room: DiscussionRoom) -> Payload: fields, identifier_fields = _GATEWAY_EVENT_FIELDS[kind] _exact_fields(payload, label=f"{kind} payload", required=fields) if kind == "room.activity" and payload.get("status") not in {"settled", "bounded"}: raise DiscussionValidationError("invalid room.activity status") for field in identifier_fields: _identifier(payload.get(field), label=field) _require_gateway_actor(actor, room, f"{kind} requires the room gateway") return payload _EVENT_VALIDATORS = { "message.user": _validate_user_event, "message.member": _validate_member_message, **dict.fromkeys(_TERMINAL_EVENT_KINDS, _validate_terminal_event), **dict.fromkeys(_GATEWAY_EVENT_FIELDS, _validate_gateway_event), lead_routing.ASSIGNMENT_EVENT_KIND: lead_routing.validate_assignment_event, router.ROUTED_EVENT_KIND: router.validate_routed_event, router.CONTINUED_EVENT_KIND: router.validate_continued_event} def _validate_event(raw: Any, *, room: DiscussionRoom, previous_seq: int) -> _ValidatedEvent: if not isinstance(raw, Mapping): raise DiscussionValidationError("room event must be an object") if raw.get("room_id") != room.room_id: raise DiscussionValidationError("room event belongs to a different room") if (seq := _positive_int(raw.get("seq"), label="event seq")) <= previous_seq: raise DiscussionValidationError("room events must be in strict sequence order") event_id = _identifier(raw.get("event_id"), label="event_id") kind, actor, payload = raw.get("kind"), raw.get("actor"), raw.get("payload") for value, expected, message in ( (kind, str, "event kind must be a string"), (actor, Mapping, "event actor must be an object"), (payload, Mapping, "event payload must be an object")): if not isinstance(value, expected): raise DiscussionValidationError(message) if kind in _EPOCH_STAMPED_KINDS and raw.get("authority_epoch") != room.authority_epoch: raise DiscussionValidationError(f"{kind} authority epoch does not match the room") if (validator := _EVENT_VALIDATORS.get(kind)) is not None: payload = validator(kind, payload, actor, room) return _ValidatedEvent(raw=raw, seq=seq, event_id=event_id, kind=kind, actor=actor, payload=payload) def _validated_events(events: Sequence[Mapping[str, Any]], *, room: DiscussionRoom) -> tuple[_ValidatedEvent, ...]: validated: list[_ValidatedEvent] = [] event_ids: set[str] = set() for raw in events: event = _validate_event(raw, room=room, previous_seq=validated[-1].seq if validated else 0) if event.event_id in event_ids: raise DiscussionValidationError("room event ids must be unique") validated.append(event) event_ids.add(event.event_id) return tuple(validated) def derive_member_watermarks( room_value: Any, events: Sequence[Mapping[str, Any]], *, local_profiles: Iterable[str] ) -> dict[tuple[str, str], int]: """Derive ``(thread_id, member_id)`` watermarks from terminal events.""" return _derive_member_watermarks( _validated_events(events, room=validate_room(room_value, local_profiles=local_profiles))) def _derive_member_watermarks(events: Sequence[_ValidatedEvent]) -> dict[tuple[str, str], int]: messages_by_id = {event.event_id: event for event in events if event.kind == "message.member"} terminal_by_task: dict[str, _ValidatedEvent] = {} watermarks: dict[tuple[str, str], int] = {} for event in events: if event.kind not in _TERMINAL_EVENT_KINDS: continue task_id = str(event.payload["task_id"]) if (previous := terminal_by_task.get(task_id)) is not None: if previous.kind != "turn.deferred": raise DiscussionValidationError(f"task '{task_id}' has more than one terminal room event") if event.kind == "turn.deferred" and int( event.payload["execution_generation"]) <= int(previous.payload["execution_generation"]): raise DiscussionValidationError(f"task '{task_id}' deferral generation did not advance") terminal_by_task[task_id] = event key = (str(event.payload["thread_id"]), str(event.payload["member_id"])) watermark = int(event.payload["seen_through_seq"]) if event.kind == "turn.settled" and not event.payload["passed"]: message = messages_by_id.get(str(event.payload["message_event_id"])) if message is None or any( message.payload.get(f) != event.payload.get(f) for f in ("task_id", "member_id", "thread_id")): raise DiscussionValidationError("turn.settled references no matching member message") discussion_seq = next((candidate.seq for candidate in events if candidate.event_id == event.payload["discussion_event_id"]), None) if discussion_seq is None: raise DiscussionValidationError("turn.settled references no matching user discussion") if watermark >= discussion_seq: watermark = max(watermark, message.seq) watermarks[key] = max(watermarks.get(key, 0), watermark) return watermarks def _member_digest(member: DiscussionMember) -> str: target = compact_json(member.target or {"kind": "local", "profile": member.profile}, ensure_ascii=False) return hashlib.sha256(f"{member.member_id}\0{member.profile}\0{member.handle}\0{target}".encode()).hexdigest()[:24] def _rotate(members: Sequence[DiscussionMember], round_index: int) -> tuple[DiscussionMember, ...]: shift = round_index % len(members) if members else 0 return tuple((*members[shift:], *members[:shift])) def _scheduled_job(event: _ValidatedEvent | None) -> str | None: """The job label of a scheduler-authored ``message.user`` event, else None (the human wrote it).""" if event is None or event.kind != "message.user" or scheduled_post_kind(event.actor) is None: return None return str(event.actor.get("display_name") or event.actor.get("id")) def _format_message(event: _ValidatedEvent, room: DiscussionRoom) -> str: if event.kind == "message.user" and (job := _scheduled_job(event)) is None: return f"User (user): {event.payload['text']}" # Scheduled output is agent-written too (often a summary of fetched content), so it gets the same # control-frame relabel as a member reply; only the human's own lines stay verbatim. text = _MEMBER_CONTROL_FRAME_RE.sub(_MEMBER_CONTROL_FRAME_RELABEL, event.payload["text"]) if event.kind == "message.user": return f'Scheduled job "{job}" (automated post, not the user): {text}' return f"@{_member_by_id(room, event.payload['member_id']).handle}: {text}" def _truncate_utf8_text(value: Any, *, max_bytes: int, suffix: str = "") -> str: text = str(value or "") if len(encoded := text.encode("utf-8")) <= max_bytes: return text # ``ignore`` drops only the incomplete trailing sequence of a cut valid-UTF-8 prefix. prefix = encoded[: max(0, max_bytes - len(suffix.encode("utf-8")))].decode("utf-8", "ignore") return prefix + suffix if prefix else suffix.strip() def _context_lines(context: Mapping[str, str] | None) -> list[str]: """Room purpose and shared notes, rendered inside the user-role turn prompt (never the system prompt).""" lines: list[str] = [] if context and context.get("purpose"): lines.append(f"Room purpose (set by the user): {context['purpose']}") if context and context.get("notes"): lines += ["Room notes (shared with every member; the user keeps them in room settings):", *(f" {line}" for line in context["notes"].splitlines())] return [*lines, ""] if lines else [] def _build_prompt( *, room: DiscussionRoom, member: DiscussionMember, messages: Sequence[_ValidatedEvent], watermark: int, seen_through_seq: int, reply_required: bool = False, context: Mapping[str, str] | None = None, addressed_by_job: str | None = None, assigned_by: DiscussionMember | None = None, routed: bool = False) -> str: delta = [event for event in messages if watermark < event.seq <= seen_through_seq][- MAX_DISCUSSION_DELTA_LINES:] peers = ", ".join(f"@{candidate.handle}" for candidate in room.members if candidate.member_id != member.member_id) opening = [ f'[Discussion: "{room.name}"] You are @{member.handle}, one participant ' f"with {peers or 'no other members'} and the user.", "", *_context_lines(context), "New messages in this thread since your last turn (oldest first):"] addressed = (f"- The room lead @{assigned_by.handle} gave the user's message to you." if assigned_by else f'- The scheduled job "{addressed_by_job}" addressed you.' if addressed_by_job else "- The room picked you to answer the user's message." if routed else "- The user directly addressed you.") participation = [ f"{addressed} Reply with your answer, result, or concrete blocker.", '- Do not return "(pass)". If you cannot proceed, explain why and what you need from the user.', ] if reply_required or assigned_by or routed else [ "- Reply with one conversational message only when you have something new worth adding.", '- If you have nothing new to add, reply with exactly "(pass)".'] rules = [ "", "Rules for this Discussion:", *participation, "- Mention a teammate by handle to pull them into the next round; do not repeat points already made.", "- Never reveal content from private conversations. Your reply is published verbatim."] fixed_bytes = len("\n".join([*opening, *rules]).encode("utf-8")) available = max(0, driver.MAX_PROMPT_BYTES - fixed_bytes - 1) selected: list[str] = [] for event in reversed(delta): line = f" {_format_message(event, room)}" if (line_bytes := len(line.encode("utf-8")) + 1) > available: if not selected and available > 32: selected.append(_truncate_utf8_text(line, max_bytes=available)) selected.append(" [Earlier content omitted to fit this turn.]") break selected.append(line) available -= line_bytes selected.reverse() if len((prompt := "\n".join([*opening, *selected, *rules])).encode("utf-8")) > driver.MAX_PROMPT_BYTES: raise DiscussionValidationError("Discussion prompt exceeds the driver limit") return prompt def _requires_direct_reply( room: DiscussionRoom, source: _ValidatedEvent | None, member: DiscussionMember, round_index: int, ) -> bool: # Only the user's initial address requires a reply. A later peer handoff may # legitimately pass after this member has already answered that user. return (round_index == 0 and source is not None and source.kind == "message.user" and member in resolve_mentions((str(source.payload["text"]),), room.members, default_all=False)) def _make_task_plan( *, room: DiscussionRoom, discussion_event: _ValidatedEvent, member: DiscussionMember, member_index: int, round_index: int, seen_through_seq: int, prompt: str, input_context: Mapping[str, Any] | None = None, attachments: Sequence[Mapping[str, Any]] = (), lead_routing: bool = False) -> DiscussionTaskPlan: turn_id = f"d{discussion_event.seq}.r{round_index}.p{member_index}.s{seen_through_seq}.m{_member_digest(member)}" if attachments: attachments = driver.validate_bound_task_manifest(list(attachments)) # A routing turn's id omits its prompt: the planner re-mints it on every replay to find its receipt, and # the prompt names the room and roster, which a rename or display-name edit changes after the turn ran. seed = compact_json({ "discussion_event_id": discussion_event.event_id, "member_id": member.member_id, "member_index": member_index, **({} if lead_routing else {"prompt_sha256": hashlib.sha256(prompt.encode("utf-8")).hexdigest()}), "room_id": room.room_id, "round_index": round_index, "seen_through_seq": seen_through_seq, "source_event_seq": discussion_event.seq, "thread_id": discussion_event.payload["thread_id"], **({"input_context": input_context} if input_context is not None else {}), **({"attachments": attachments} if attachments else {}), **({"lead_routing": True} if lead_routing else {})}) identity = driver.TaskIdentity( room_id=room.room_id, task_id=f"dtask:{hashlib.sha256(seed.encode('utf-8')).hexdigest()[:48]}", thread_id=str(discussion_event.payload["thread_id"]), turn_id=turn_id) payload = { "target_member_id": member.member_id, "target_profile": member.profile, "prompt": prompt, "source_event_seq": discussion_event.seq} if attachments: payload["attachments"] = list(attachments) if input_context is not None: payload["input_context"] = dict(input_context) if lead_routing: payload["lead_routing"] = True return DiscussionTaskPlan( identity, payload, discussion_event.event_id, member, member_index, round_index, seen_through_seq) def _pending_discussion(validated: Sequence[_ValidatedEvent]) -> _ValidatedEvent | None: """Oldest latest-per-thread user message not stopped and not yet completed. A ``room.continued`` reopens a discussion its earlier activity completed (Continue at the cap).""" stopped_through_seq = max((event.seq for event in validated if event.kind == "room.stop_requested"), default=0) continued_at = router.continued_through(validated) completed_discussion_ids = { str(event.payload["discussion_event_id"]) for event in validated if event.kind == "room.activity" and event.payload.get("status") in {"settled", "bounded"} and event.seq > continued_at.get(str(event.payload["discussion_event_id"]), 0)} latest_by_thread = { str(event.payload["thread_id"]): event for event in validated if event.kind == "message.user"} return next(( event for event in sorted(latest_by_thread.values(), key=lambda item: item.seq) if event.seq > stopped_through_seq and event.event_id not in completed_discussion_ids), None) def _thread_messages( validated: Sequence[_ValidatedEvent], discussion: _ValidatedEvent ) -> tuple[tuple[_ValidatedEvent, ...], tuple[_ValidatedEvent, ...], tuple[_ValidatedEvent, ...]]: """Return (thread messages, messages since the discussion, this discussion's member messages).""" thread_id = str(discussion.payload["thread_id"]) committed_member_message_ids = { str(event.payload["message_event_id"]) for event in validated if event.kind == "turn.settled" and event.payload.get("message_event_id") is not None} # Publication writes the visible member message before the terminal event. # A crash in that gap leaves the message in the log, but it is not committed # policy input yet: ignoring it reproduces the original task coordinates so # the caller can inspect the terminal driver row and finish publication. thread_messages = tuple( event for event in validated if event.payload.get("thread_id") == thread_id and ( event.kind == "message.user" or (event.kind == "message.member" and event.event_id in committed_member_message_ids))) return thread_messages, tuple(event for event in thread_messages if event.seq >= discussion.seq), tuple( event for event in thread_messages if event.kind == "message.member" and event.payload.get("discussion_event_id") == discussion.event_id) def _effective_watermarks( validated: Sequence[_ValidatedEvent], initial_watermarks: Mapping[tuple[str, str], int] | None ) -> dict[tuple[str, str], int]: watermarks = { (str(thread_id), str(member_id)): int(value) for (thread_id, member_id), value in (initial_watermarks or {}).items() if int(value) >= 0} for key, value in _derive_member_watermarks(validated).items(): watermarks[key] = max(watermarks.get(key, 0), value) return watermarks def _event_attachments(event: _ValidatedEvent, member: DiscussionMember) -> list[dict[str, Any]]: if event.kind == "message.member": if event.payload["member_id"] == member.member_id: return [] recipients = event.payload.get("recipient_member_ids") if recipients is not None and member.member_id not in recipients: return [] return [{**attachment, "event_id": event.event_id} for attachment in event.payload.get("attachments", [])] def _bounded_task_delta(messages: Sequence[_ValidatedEvent], *, watermark: int, member: DiscussionMember) -> tuple[list[_ValidatedEvent], list[dict[str, Any]]]: from gateway.hosted_room_attachments import MAX_TASK_ATTACHMENTS, MAX_TASK_ATTACHMENT_BYTES selected: list[_ValidatedEvent] = [] attachments: list[dict[str, Any]] = [] size = 0 for event in messages: if event.seq <= watermark: continue entries = _event_attachments(event, member) next_size = size + sum(item["size"] for item in entries) if len(attachments) + len(entries) > MAX_TASK_ATTACHMENTS or next_size > MAX_TASK_ATTACHMENT_BYTES: break # Each validated message fits; consume only whole event prefixes. selected.append(event) attachments.extend(entries) size = next_size return selected, attachments def _first_round_responders(discussion: _ValidatedEvent, room: DiscussionRoom) -> tuple[DiscussionMember, ...]: """The human's message with no mention addresses everyone. A scheduled post is only a message in the room: it pulls in exactly the members it @mentions, and a failure notice pulls in nobody.""" scheduled = scheduled_post_kind(discussion.actor) if scheduled == "notice": return () return resolve_mentions((str(discussion.payload["text"]),), room.members, default_all=scheduled is None) @dataclass(frozen=True) class _LeadRound: """Lead routing for one discussion: the routing turn still to run, or who the lead gave it to.""" task: DiscussionTaskPlan | None responders: tuple[DiscussionMember, ...] lead: DiscussionMember routing_task_id: str def _lead_round( room: DiscussionRoom, discussion: _ValidatedEvent, validated: Sequence[_ValidatedEvent], context: Mapping[str, str]) -> _LeadRound | None: """None unless the room routes through a lead and this message goes to it (``hosted_room_lead``).""" lead = lead_routing.lead_member(room, context) if lead is None or not lead_routing.routes_through_lead(discussion, room, validated): return None prompt = lead_routing.routing_prompt( room=room, lead=lead, discussion=discussion, context_lines=_context_lines(context)) task = _make_task_plan(room=room, discussion_event=discussion, member=lead, member_index=0, round_index=0, seen_through_seq=discussion.seq - 1, prompt=prompt, lead_routing=True) chosen = lead_routing.first_round_members(room, lead, validated, discussion.event_id, task.identity.task_id) return _LeadRound(task if chosen is None else None, chosen or (), lead, task.identity.task_id) def plan_next_task( room_value: Any, events: Sequence[Mapping[str, Any]], *, local_profiles: Iterable[str], initial_watermarks: Mapping[tuple[str, str], int] | None = None, freeze_input_context: bool = False, limits: DiscussionLimits = DiscussionLimits(), room_context: Mapping[str, Any] | None = None, ) -> DiscussionDecision: """Replay the complete room log and return at most one next member task. ``room_context`` is the room settings in force when the pending discussion opened (``hosted_room_context.room_context``).""" room = validate_room(room_value, local_profiles=local_profiles) try: context = validate_context(**{key: str((room_context or {}).get(key) or default) for key, default in ( ("purpose", ""), ("notes", ""), ("routing", "everyone"), ("lead_member_id", ""))}) except ValueError as exc: raise DiscussionValidationError(str(exc)) from exc validated = _validated_events(events, room=room) if (discussion := _pending_discussion(validated)) is None: return DiscussionDecision(status="idle", reason="no_pending_user_event") thread_id = str(discussion.payload["thread_id"]) continues = router.continue_count(validated, discussion.event_id) # Each Continue grants one more full budget of rounds and messages for the same discussion. max_rounds, max_messages = limits.max_rounds * (continues + 1), limits.max_messages * (continues + 1) decide = partial( DiscussionDecision, discussion_event_id=discussion.event_id, source_event_seq=discussion.seq, thread_id=thread_id, continues=continues) thread_messages, discussion_messages, member_messages = _thread_messages(validated, discussion) if len(member_messages) >= max_messages: return decide("bounded", "max_messages") routed = router.routed_responders(room, discussion, validated, context) if routed is router.ROUTE_PENDING: # The router's answer is recorded as ``room.routed`` before any turn is planned, so replay never re-asks. return decide("route", "router_pending") if (lead_round := _lead_round(room, discussion, validated, context)) is not None and lead_round.task: return decide("task", "lead_routing", task=lead_round.task) # The lead's routing receipt is not its round-0 turn: a lead that gave the message to itself still answers. routing_task_id = lead_round.routing_task_id if lead_round else None terminals = { (int(event.payload["round_index"]), str(event.payload["member_id"])) for event in validated if event.kind in _TERMINAL_EVENT_KINDS and event.payload.get("discussion_event_id") == discussion.event_id and event.payload.get("task_id") != routing_task_id} watermarks = _effective_watermarks(validated, initial_watermarks) resume_round = router.resume_round(validated, discussion.event_id, member_messages) for round_index in range(max_rounds): # The user's message selects the first round, with no mention meaning # everyone. Later rounds are opt-in: only a peer explicitly cited by a # Bot and not heard from afterward gets another turn. Every member's # watermark remains intact, so a peer cited later still receives the # complete bounded transcript delta without consuming turns meanwhile. responders = ( (lead_round.responders if lead_round else routed if routed is not None else _first_round_responders(discussion, room)) if round_index == 0 else _unaddressed_member_mentions(discussion_messages, room)) if not responders and round_index == resume_round: # The round after the pause: with nobody cited, the whole room picks the discussion back up. responders = room.members for member_index, member in enumerate(_rotate(responders, round_index)): watermark = watermarks.get((thread_id, member.member_id), 0) delta, attachments = _bounded_task_delta(thread_messages, watermark=watermark, member=member) if not delta or ((round_index, member.member_id) in terminals and not attachments): continue seen_through_seq = delta[-1].seq prompt = _build_prompt( room=room, member=member, messages=thread_messages, watermark=watermark, seen_through_seq=seen_through_seq, context=context, addressed_by_job=_scheduled_job(discussion), reply_required=_requires_direct_reply(room, discussion, member, round_index), assigned_by=lead_round.lead if lead_round and round_index == 0 and member != lead_round.lead else None, routed=round_index == 0 and routed is not None and len(routed) < len(room.members)) return decide("task", "member_turn", task=_make_task_plan( room=room, discussion_event=discussion, member=member, member_index=member_index, round_index=round_index, seen_through_seq=seen_through_seq, prompt=prompt, attachments=attachments, input_context=(validate_task_input({"watermark": watermark, "event_seqs": [event.seq for event in delta]}) if freeze_input_context or attachments else None))) if not any(int(event.payload["round_index"]) == round_index for event in member_messages): return decide("settled", "silent_round") if round_index == max_rounds - 1: return decide("bounded", "max_rounds") raise AssertionError("bounded Discussion loop exhausted unexpectedly") def _reconstructed_lead_routing(payload: Mapping[str, Any], match: re.Match[str], source_event_seq: int) -> bool: """A persisted routing turn keeps the only coordinates ``_lead_round`` mints: round 0, position 0, seeing through the message before its own, with no frozen input or files.""" if "lead_routing" not in payload: return False if payload["lead_routing"] is not True or (match.group("round"), match.group("position")) != ("0", "0") or ( int(match.group("seen")) != source_event_seq - 1 or {"input_context", "attachments"} & set(payload)): raise DiscussionReconstructionError("lead routing task does not match its turn_id") return True def reconstruct_task_plan( room_value: Any, events: Sequence[Mapping[str, Any]], task: Mapping[str, Any], *, local_profiles: Iterable[str] ) -> DiscussionTaskPlan: """Reconstruct and verify one persisted driver task after a restart.""" room = validate_room(room_value, local_profiles=local_profiles) validated = _validated_events(events, room=room) identity, payload = task.get("identity"), task.get("payload") if not isinstance(identity, driver.TaskIdentity) or not isinstance(payload, Mapping): raise DiscussionReconstructionError("driver task has no valid identity or payload") fields = frozenset(payload) if not driver._TASK_PAYLOAD_REQUIRED_FIELDS <= fields <= ( driver._TASK_PAYLOAD_REQUIRED_FIELDS | driver._TASK_PAYLOAD_OPTIONAL_FIELDS): raise DiscussionReconstructionError("driver task payload shape changed") if (match := _TURN_ID_RE.fullmatch(identity.turn_id)) is None: raise DiscussionReconstructionError("turn_id is not a Discussion coordinate") source_event_seq = int(match.group("source")) if payload.get("source_event_seq") != source_event_seq: raise DiscussionReconstructionError("task source event does not match turn_id") discussion = next((e for e in validated if e.seq == source_event_seq and e.kind == "message.user"), None) if discussion is None: raise DiscussionReconstructionError("task source user event is missing") if identity.room_id != room.room_id or identity.thread_id != discussion.payload["thread_id"]: raise DiscussionReconstructionError("task identity does not match its room thread") profile, target_member_id = payload.get("target_profile"), payload.get("target_member_id") member = next(( m for m in room.members if m.profile == profile and (target_member_id is None or m.member_id == target_member_id)), None) if member is None or _member_digest(member) != match.group("member"): raise DiscussionReconstructionError("task target member does not match turn_id") if not isinstance(prompt := payload.get("prompt"), str) or not prompt.strip(): raise DiscussionReconstructionError("task prompt is missing") if len(prompt.encode("utf-8")) > driver.MAX_PROMPT_BYTES: raise DiscussionReconstructionError("task prompt exceeds the driver limit") input_context = None if "input_context" in payload: try: input_context = validate_task_input(payload["input_context"]) except ValueError as exc: raise DiscussionReconstructionError(str(exc)) from exc if input_context["event_seqs"][-1] != int(match.group("seen")): raise DiscussionReconstructionError("task input does not match turn_id") message_seqs = {event.seq for event in validated if event.kind in {"message.user", "message.member"} and event.payload.get("thread_id") == identity.thread_id} if any(seq not in message_seqs for seq in input_context["event_seqs"]): raise DiscussionReconstructionError("task input message is missing") attachments: list[dict[str, Any]] = [] if "attachments" in payload: if input_context is None: raise DiscussionReconstructionError("attachment task requires frozen input_context") by_seq = {event.seq: event for event in validated} attachments = [item for seq in input_context["event_seqs"] for item in _event_attachments(by_seq[seq], member)] lead_routing = _reconstructed_lead_routing(payload, match, source_event_seq) reconstructed = _make_task_plan( room=room, discussion_event=discussion, member=member, member_index=int(match.group("position")), round_index=int(match.group("round")), seen_through_seq=int(match.group("seen")), prompt=prompt, input_context=input_context, attachments=attachments, lead_routing=lead_routing) if reconstructed.identity != identity or dict(reconstructed.payload) != dict(payload): raise DiscussionReconstructionError("driver task failed deterministic reconstruction") return reconstructed def _turn_coordinates(task: DiscussionTaskPlan) -> dict[str, Any]: """The coordinate fields every member message and terminal event carries.""" return { "discussion_event_id": task.discussion_event_id, "member_id": task.member.member_id, "member_index": task.member_index, "round_index": task.round_index, "task_id": task.identity.task_id, "thread_id": task.identity.thread_id, "turn_id": task.identity.turn_id} def _terminal_text(result: Any, *, field: str, fallback: str) -> str: if isinstance(result, Mapping): result = result.get(field) if field != "error" or result.get("error") is not None else result.get("text") return str(result or "").strip() or fallback # -- per-status terminal payload builders (dispatched by plan_publication) ----- # Each returns (extra terminal payload fields, visible effects to publish first). Effects = tuple[dict[str, Any], list[EventPlan]] def _settled_effects( result: Any, *, task: DiscussionTaskPlan, room: DiscussionRoom, message_event_id: str, **_: Any) -> Effects: text = _truncate_utf8_text( _terminal_text(result, field="text", fallback=""), max_bytes=MAX_MEMBER_TEXT_BYTES, suffix=_TRUNCATED_REPLY_NOTICE) if is_pass_text(text): return {"message_event_id": None, "passed": True}, [] return {"message_event_id": message_event_id, "passed": False}, [EventPlan( event_id=message_event_id, kind="message.member", actor=_member_actor(task.member), payload={**_turn_coordinates(task), "text": text}, authority_gateway_id=room.gateway_id, authority_epoch=room.authority_epoch)] def _failed_effects(result: Any, **_: Any) -> Effects: error_text = _terminal_text(result, field="error", fallback="member turn failed") from tools.bot_failure_reasons import classify_agent_error supplied_reason = ( str(result.get("reason_code") or result.get("reason") or "").strip() if isinstance(result, Mapping) else "") reason_code = supplied_reason if supplied_reason in _all_failure_reasons() else classify_agent_error(error_text) return {"error": error_text, "reason_code": reason_code}, [] def _cancelled_effects(result: Any, *, newer_same_thread: bool, **_: Any) -> Effects: if newer_same_thread: return {"reason": "superseded_by_newer_user_event"}, [] return {"reason": _terminal_text(result, field="reason", fallback="member turn cancelled")}, [] def _deferred_effects(result: Any, *, execution_generation: int | None, **_: Any) -> Effects: reason = _terminal_text(result, field="reason", fallback="member_unavailable") return {"execution_generation": execution_generation, "reason": reason}, [] _TERMINAL_EFFECTS = { "settled": _settled_effects, "failed": _failed_effects, "cancelled": _cancelled_effects, "deferred": _deferred_effects} def plan_publication( room_value: Any, events: Sequence[Mapping[str, Any]], task: DiscussionTaskPlan, *, status: TerminalKind, result: Any = None, execution_generation: int | None = None, local_profiles: Iterable[str]) -> PublicationPlan: """Plan idempotent room effects for one terminal driver task. A newer user event in the same thread supersedes a late result: the task stays terminal in driver state, but only a deterministic cancellation is published so stale prose and its watermark cannot hide it. """ room = validate_room(room_value, local_profiles=local_profiles) validated = _validated_events(events, room=room) for failed, message in ( (task.identity.room_id != room.room_id, "task belongs to a different room"), (task.member not in room.members, "task member is not in the frozen roster"), (status not in _TERMINAL_EFFECTS, "invalid terminal publication status")): if failed: raise DiscussionValidationError(message) if status == "deferred": _bounded_int(execution_generation, message="deferred publication requires an execution generation", low=1) newer_same_thread = any( event.kind == "message.user" and event.seq > int(task.payload["source_event_seq"]) and event.payload.get("thread_id") == task.identity.thread_id for event in validated) effective_status: TerminalKind = ("cancelled" if newer_same_thread and status != "deferred" else status) source = next((event for event in validated if event.event_id == task.discussion_event_id), None) if (effective_status == "settled" and _requires_direct_reply(room, source, task.member, task.round_index) and is_pass_text(_terminal_text(result, field="text", fallback=""))): # The execution completed, but did not answer the user. Publish that # failure from the durable receipt without replaying any tools or model calls. effective_status = "failed" result = {"error": f"@{task.member.handle} was directly addressed but returned no visible reply."} digest = task.identity.task_id.removeprefix("dtask:") terminal_event_id = ( f"ddeferred:{digest}:g{execution_generation}" if effective_status == "deferred" else f"dterminal:{digest}") routing = lead_routing.is_routing_task(task) # A routing answer is never published as a reply: it becomes the room.assignment ahead of the receipt. extra, effects = _TERMINAL_EFFECTS[effective_status]( "(pass)" if routing and effective_status == "settled" else result, task=task, room=room, message_event_id=f"dmessage:{digest}", newer_same_thread=newer_same_thread, execution_generation=execution_generation) if routing: effects = lead_routing.assignment_effect(result, task=task, room=room, status=effective_status) + effects terminal_kind = f"turn.{effective_status}" effects.append(EventPlan( event_id=terminal_event_id, kind=terminal_kind, actor={"kind": "gateway", "id": room.gateway_id}, payload={**_turn_coordinates(task), "seen_through_seq": task.seen_through_seq, **extra}, authority_gateway_id=room.gateway_id, authority_epoch=room.authority_epoch)) return PublicationPlan(task_id=task.identity.task_id, terminal_kind=terminal_kind, events=tuple(effects))