hosted_room_discussion.py 57 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057
  1. """Deterministic policy for same-gateway hosted-room Discussions.
  2. Pure (no I/O, transport or model knowledge): a frozen local roster plus the complete typed room log yields
  3. at most one next driver task. Discussion coordinates live in deterministic ``TaskIdentity`` values and typed
  4. terminal events rather than a widened driver payload, so a restart reconstructs tasks from durable state.
  5. Callers must reconcile terminal driver rows into publication plans before asking for the next task.
  6. """
  7. from __future__ import annotations
  8. import hashlib
  9. import re
  10. from collections.abc import Iterable, Mapping, Sequence
  11. from dataclasses import asdict, dataclass
  12. from functools import partial
  13. from typing import Any, Literal
  14. from agent.prompt_builder import CONTROL_FRAME_OPENERS
  15. from gateway import hosted_room_driver as driver
  16. from gateway import hosted_room_lead as lead_routing
  17. from gateway import hosted_room_router as router
  18. from gateway import hosted_rooms
  19. from gateway import hosted_rooms_common as common
  20. from gateway.hosted_room_context import scheduled_post_kind, validate_context
  21. from gateway.hosted_room_task_input import validate_task_input
  22. from gateway.hosted_rooms_common import compact_json
  23. MAX_DISCUSSION_MEMBERS = 6
  24. MIN_DISCUSSION_MEMBERS = 2
  25. MAX_DISCUSSION_ROUNDS = 3
  26. MAX_DISCUSSION_MESSAGES = 10
  27. MAX_DISCUSSION_DELTA_LINES = 24
  28. MAX_USER_TEXT_BYTES = 64 * 1024
  29. MAX_MEMBER_TEXT_BYTES = 64 * 1024
  30. _TRUNCATED_REPLY_NOTICE = "\n\n[Reply truncated. Ask the Bot to share the full result as a file.]"
  31. Payload = Mapping[str, Any]
  32. DecisionStatus = Literal["idle", "task", "settled", "bounded", "route"]
  33. TerminalKind = Literal["settled", "failed", "cancelled", "deferred"]
  34. _MENTION_RE = re.compile(r"@([A-Za-z0-9][A-Za-z0-9._:-]*)", re.IGNORECASE)
  35. # Openers of Hermes' own control frames (agent.prompt_builder.CONTROL_FRAME_OPENERS: the steer marker, the
  36. # compaction handoff, runtime/system notes, background-process and prior-context frames). A member reply is
  37. # republished to every peer inside a role=user prompt, so a reply reproducing one of these reads as harness
  38. # input to the peers; the opener is relabelled visibly (the words stay, the exact trusted shape does not).
  39. # Genuine user lines are never touched. Keep in sync with apps/desktop hermes-bots/group-round-prompt.ts.
  40. _MEMBER_CONTROL_FRAME_RE = re.compile(
  41. r"\[(?=" + "|".join(opener.replace("]", r"\]") for opener in CONTROL_FRAME_OPENERS) + ")",
  42. re.IGNORECASE,
  43. )
  44. _MEMBER_CONTROL_FRAME_RELABEL = "[member-quoted "
  45. _TURN_ID_RE = re.compile(
  46. r"^d(?P<source>[1-9][0-9]*)\.r(?P<round>0|[1-9][0-9]*)\."
  47. r"p(?P<position>[0-5])\.s(?P<seen>[1-9][0-9]*)\."
  48. r"m(?P<member>[0-9a-f]{24})$")
  49. def turn_round(turn_id: str) -> int | None:
  50. """The 0-based round a Discussion turn id names, or None for a turn id of another shape."""
  51. match = _TURN_ID_RE.fullmatch(turn_id)
  52. return int(match.group("round")) if match else None
  53. _TARGET_FIELDS = {
  54. "local": frozenset({"kind", "profile"}),
  55. "peer": frozenset({"kind", "peer_id", "installation_id", "profile", "capability_digest"})}
  56. _REMOTE_MEMBER_FIELDS = frozenset({
  57. "connectionId", "connectionKind", "connectionLabel", "connection_id", "connection_kind", "connection_label",
  58. "remoteSource", "route", "sourceMissing", "sourceReachable", "sourceScoped", "targetProfile", "target_profile"})
  59. _USER_PAYLOAD_FIELDS = frozenset({"text", "thread_id"})
  60. _TURN_COORDINATE_FIELDS = frozenset(
  61. {"discussion_event_id", "member_id", "member_index", "round_index", "task_id", "thread_id", "turn_id", })
  62. _MEMBER_MESSAGE_FIELDS = _TURN_COORDINATE_FIELDS | {"text"}
  63. _TERMINAL_FIELDS = { # kind -> exact payload fields (coordinates + seen_through_seq + per-kind extras)
  64. kind: _TURN_COORDINATE_FIELDS | {"seen_through_seq", *extra} for kind, extra in (
  65. ("turn.settled", ("message_event_id", "passed")), ("turn.failed", ("error",)),
  66. ("turn.cancelled", ("reason",)), ("turn.deferred", ("execution_generation", "reason")))}
  67. _TERMINAL_OPTIONAL_FIELDS = {"turn.failed": frozenset({"reason_code"})}
  68. _TERMINAL_EVENT_KINDS = frozenset(_TERMINAL_FIELDS)
  69. # Gateway-authored control events: kind -> (exact payload fields, identifier fields).
  70. _GATEWAY_EVENT_FIELDS = {
  71. "room.activity": (
  72. frozenset({"status", "reason_code", "thread_id", "discussion_event_id"}),
  73. ("reason_code", "thread_id", "discussion_event_id")),
  74. "room.stop_requested": (frozenset({"cancel_id"}), ("cancel_id",))}
  75. _EPOCH_STAMPED_KINDS = _TERMINAL_EVENT_KINDS | {
  76. "message.member", lead_routing.ASSIGNMENT_EVENT_KIND, router.ROUTED_EVENT_KIND, router.CONTINUED_EVENT_KIND,
  77. *_GATEWAY_EVENT_FIELDS}
  78. class DiscussionPolicyError(ValueError): """Base class for invalid policy input or unreconstructable state."""
  79. class DiscussionValidationError(DiscussionPolicyError):
  80. """Raised when a room, roster, payload, or typed event is malformed."""
  81. class DiscussionReconstructionError(DiscussionPolicyError):
  82. """Raised when a persisted task cannot be reproduced from durable state."""
  83. @dataclass(frozen=True)
  84. class DiscussionLimits:
  85. """Finite per-user-send scheduling ceilings, separate from replay validation."""
  86. max_rounds: int = MAX_DISCUSSION_ROUNDS
  87. max_messages: int = MAX_DISCUSSION_MESSAGES
  88. def __post_init__(self) -> None:
  89. _positive_int(self.max_rounds, label="hosted_rooms.discussion.max_rounds")
  90. _positive_int(self.max_messages, label="hosted_rooms.discussion.max_messages")
  91. @dataclass(frozen=True)
  92. class DiscussionMember:
  93. """One immutable local or peer member of the hosted room."""
  94. member_id: str
  95. profile: str
  96. handle: str
  97. display_name: str = ""
  98. target: Mapping[str, Any] | None = None
  99. @dataclass(frozen=True)
  100. class DiscussionRoom:
  101. """Validated policy projection of one active hosted room."""
  102. room_id: str
  103. name: str
  104. members: tuple[DiscussionMember, ...]
  105. gateway_id: str
  106. authority_epoch: int
  107. @dataclass(frozen=True)
  108. class DiscussionTaskPlan:
  109. """One deterministic member turn compatible with the driver schema."""
  110. identity: driver.TaskIdentity
  111. payload: Mapping[str, Any]
  112. discussion_event_id: str
  113. member: DiscussionMember
  114. member_index: int
  115. round_index: int
  116. seen_through_seq: int
  117. @dataclass(frozen=True)
  118. class DiscussionDecision:
  119. """Current result of replaying one room's Discussion policy."""
  120. status: DecisionStatus
  121. reason: str
  122. discussion_event_id: str | None = None
  123. source_event_seq: int | None = None
  124. thread_id: str | None = None
  125. task: DiscussionTaskPlan | None = None
  126. #: How many times the user granted this discussion another budget (``room.continued``).
  127. continues: int = 0
  128. @dataclass(frozen=True)
  129. class EventPlan:
  130. """One idempotent append for :func:`gateway.hosted_rooms.append_event`."""
  131. event_id: str
  132. kind: str
  133. actor: Mapping[str, str]
  134. payload: Mapping[str, Any]
  135. authority_gateway_id: str
  136. authority_epoch: int
  137. def append_kwargs(self, room_id: str) -> dict[str, Any]:
  138. """Return keyword arguments accepted by ``append_event`` (field order matches the dataclass)."""
  139. return {"room_id": room_id, **asdict(self)}
  140. @dataclass(frozen=True)
  141. class PublicationPlan:
  142. """Ordered visible and terminal effects for one driver task."""
  143. task_id: str
  144. terminal_kind: str
  145. events: tuple[EventPlan, ...]
  146. @dataclass(frozen=True)
  147. class _ValidatedEvent:
  148. raw: Payload
  149. seq: int
  150. event_id: str
  151. kind: str
  152. actor: Payload
  153. payload: Payload
  154. _identifier = partial(common.identifier, error=DiscussionValidationError, max_chars=driver.MAX_IDENTIFIER_CHARS)
  155. _exact_fields = partial(common.exact_fields, error=DiscussionValidationError)
  156. _bounded_int = partial(common.bounded_int, error=DiscussionValidationError)
  157. _text = partial(common.text, error=DiscussionValidationError)
  158. def _positive_int(value: Any, *, label: str) -> int:
  159. return _bounded_int(value, message=f"{label} must be a positive integer", low=1)
  160. def _zero_based_int(value: Any, *, label: str, maximum: int) -> int:
  161. return _bounded_int(value, message=f"{label} must be an integer between 0 and {maximum}", high=maximum)
  162. def _peer_id(member: DiscussionMember) -> str | None:
  163. target = member.target
  164. return target.get("peer_id") if target and target.get("kind") == "peer" else None
  165. def _member_actor(member: DiscussionMember, *, display_name: bool = True) -> dict[str, Any]:
  166. """Member actor for the room log; ``connection_id`` (and ``display_name``) only when present."""
  167. actor = {"kind": "member", "id": member.member_id, "profile": member.profile}
  168. if (peer_id := _peer_id(member)) is not None:
  169. actor["connection_id"] = peer_id
  170. if display_name and member.display_name:
  171. actor["display_name"] = member.display_name
  172. return actor
  173. def _all_failure_reasons() -> frozenset[str]:
  174. from tools.bot_failure_reasons import ALL_REASONS
  175. return ALL_REASONS
  176. def validate_user_payload(value: Any) -> dict[str, Any]:
  177. """Validate and normalize the exact ``message.user`` Discussion payload."""
  178. payload = _exact_fields(value, label="user payload", required=_USER_PAYLOAD_FIELDS, optional={"attachments"})
  179. normalized: dict[str, Any] = {"thread_id": _identifier(payload["thread_id"], label="thread_id")}
  180. if "attachments" in payload:
  181. normalized["attachments"] = _message_manifest(payload["attachments"])
  182. text = payload["text"]
  183. if not isinstance(text, str) or len(text.encode("utf-8")) > MAX_USER_TEXT_BYTES:
  184. raise DiscussionValidationError("user payload text must be a bounded string")
  185. if not text.strip() and not normalized.get("attachments"):
  186. raise DiscussionValidationError("user payload must contain text or attachments")
  187. normalized["text"] = text.strip()
  188. return normalized
  189. def _message_manifest(value: Any) -> list[dict[str, Any]]:
  190. from gateway.hosted_room_attachments import validate_manifest
  191. try:
  192. return validate_manifest(value)
  193. except ValueError as exc:
  194. raise DiscussionValidationError(str(exc)) from exc
  195. def _validate_member_target(value: Any, *, profile: str, known_profiles: set[str], index: int) -> dict[str, Any]:
  196. if value is None:
  197. if profile not in known_profiles:
  198. raise DiscussionValidationError(f"member {index} profile '{profile}' is not local to this gateway")
  199. return {"kind": "local", "profile": profile}
  200. if not isinstance(value, Mapping):
  201. raise DiscussionValidationError(f"member {index} target must be an object")
  202. kind = value.get("kind")
  203. if kind not in _TARGET_FIELDS:
  204. raise DiscussionValidationError(f"member {index} target kind must be local or peer")
  205. target = _exact_fields(value, label=f"member {index} {kind} target", required=_TARGET_FIELDS[kind])
  206. target_profile = _identifier(target["profile"], label=f"member {index} target profile")
  207. if kind == "local":
  208. if target_profile != profile:
  209. raise DiscussionValidationError(f"member {index} local target profile does not match member profile")
  210. if profile not in known_profiles:
  211. raise DiscussionValidationError(f"member {index} profile '{profile}' is not local to this gateway")
  212. return {"kind": "local", "profile": profile}
  213. if target_profile != profile:
  214. raise DiscussionValidationError(f"member {index} peer target profile does not match member profile")
  215. digest = target["capability_digest"]
  216. if not isinstance(digest, str) or not re.fullmatch(r"[0-9a-f]{64}", digest):
  217. raise DiscussionValidationError(f"member {index} capability_digest must be a sha256 digest")
  218. return {
  219. "kind": "peer", "peer_id": _identifier(target["peer_id"], label=f"member {index} peer_id"),
  220. "installation_id": _identifier(target["installation_id"], label=f"member {index} installation_id"),
  221. "profile": target_profile, "capability_digest": digest}
  222. def _validate_member(raw: Any, index: int, known_profiles: set[str]) -> DiscussionMember:
  223. if not isinstance(raw, Mapping):
  224. raise DiscussionValidationError(f"member {index} must be an object")
  225. if remote_fields := frozenset(raw) & _REMOTE_MEMBER_FIELDS:
  226. raise DiscussionValidationError(
  227. f"member {index} contains cross-gateway fields: {', '.join(sorted(remote_fields))}")
  228. member = _exact_fields(
  229. raw, label=f"member {index}", required=frozenset({"member_id", "profile", "handle"}),
  230. optional=frozenset({"display_name", "target"}))
  231. member_id, profile, handle = (
  232. _identifier(member[field], label=f"member {index} {label}")
  233. for field, label in (("member_id", "id"), ("profile", "profile"), ("handle", "handle")))
  234. target = _validate_member_target(member.get("target"), profile=profile, known_profiles=known_profiles, index=index)
  235. if not isinstance(display_name := member.get("display_name", ""), str):
  236. raise DiscussionValidationError(f"member {index} display_name must be a string")
  237. if len(display_name := display_name.strip()) > hosted_rooms.MAX_ACTOR_LABEL_CHARS:
  238. raise DiscussionValidationError(f"member {index} display_name is too long")
  239. return DiscussionMember(member_id, profile, handle, display_name, target)
  240. def validate_roster(value: Any, *, local_profiles: Iterable[str]) -> tuple[DiscussionMember, ...]:
  241. """Validate a frozen 2-6 member roster of profiles on this gateway."""
  242. if not isinstance(value, list):
  243. raise DiscussionValidationError("members must be a list")
  244. if not MIN_DISCUSSION_MEMBERS <= len(value) <= MAX_DISCUSSION_MEMBERS:
  245. raise DiscussionValidationError(
  246. f"members must contain between {MIN_DISCUSSION_MEMBERS} and {MAX_DISCUSSION_MEMBERS} entries")
  247. known_profiles = {_identifier(profile, label="local profile") for profile in local_profiles}
  248. members: list[DiscussionMember] = []
  249. targets: set[str] = set()
  250. handles: set[str] = {"all", "everyone"} # reserved mention handles
  251. member_ids: set[str] = set()
  252. for index, raw in enumerate(value):
  253. member = _validate_member(raw, index, known_profiles)
  254. unique = "profiles" if member.target.get("kind") == "local" else "targets"
  255. for key, seen, message in (
  256. (compact_json(member.target, ensure_ascii=False).casefold(), targets, f"member {unique} must be unique"),
  257. (member.handle.casefold(), handles, "member handles must be unique and cannot reserve @all or @everyone"),
  258. (member.member_id.casefold(), member_ids, "member ids must be unique")):
  259. if key in seen:
  260. raise DiscussionValidationError(message)
  261. seen.add(key)
  262. members.append(member)
  263. return tuple(members)
  264. def validate_room(value: Any, *, local_profiles: Iterable[str]) -> DiscussionRoom:
  265. """Project a hosted-room row into the strict same-gateway policy shape."""
  266. if not isinstance(value, Mapping):
  267. raise DiscussionValidationError("room must be an object")
  268. if value.get("disbanded_at") is not None:
  269. raise DiscussionValidationError("room is disbanded")
  270. room_id = _identifier(value.get("room_id"), label="room_id")
  271. if not isinstance(name := value.get("name"), str) or not name.strip():
  272. raise DiscussionValidationError("room name must be a non-empty string")
  273. if len(name := name.strip()) > hosted_rooms.MAX_ROOM_NAME_CHARS:
  274. raise DiscussionValidationError("room name is too long")
  275. gateway_id = _identifier(value.get("authority_gateway_id"), label="authority_gateway_id")
  276. authority_epoch = _positive_int(value.get("authority_epoch"), label="authority_epoch")
  277. members = validate_roster(value.get("members"), local_profiles=local_profiles)
  278. return DiscussionRoom(room_id, name, members, gateway_id, authority_epoch)
  279. def is_pass_text(value: Any) -> bool:
  280. """Return whether a settled member result is Discussion silence."""
  281. text = str(value or "").strip()
  282. return not text or re.fullmatch(r"\(?\s*pass\s*\)?\.?", text, re.IGNORECASE) is not None
  283. def resolve_mentions(
  284. texts: Iterable[str], members: Sequence[DiscussionMember], *, default_all: bool = True
  285. ) -> tuple[DiscussionMember, ...]:
  286. """Resolve member handles deterministically against the frozen roster."""
  287. by_handle = {member.handle.casefold(): member for member in members}
  288. mentioned: set[str] = set()
  289. everyone = False
  290. for text in texts:
  291. for match in _MENTION_RE.finditer(str(text or "")):
  292. handle = match.group(1).casefold()
  293. if handle in {"all", "everyone"}:
  294. everyone = True
  295. elif handle in by_handle:
  296. mentioned.add(handle)
  297. if everyone or (default_all and not mentioned):
  298. return tuple(members)
  299. return tuple(member for member in members if member.handle.casefold() in mentioned)
  300. def _unaddressed_member_mentions(
  301. messages: Sequence[_ValidatedEvent], room: DiscussionRoom) -> tuple[DiscussionMember, ...]:
  302. """Return peers explicitly cited by a Bot and not heard from afterward."""
  303. cited_at: dict[str, int] = {}
  304. last_post_at: dict[str, int] = {}
  305. for event in messages:
  306. if event.kind != "message.member":
  307. continue
  308. speaker_id = str(event.payload["member_id"])
  309. last_post_at[speaker_id] = event.seq
  310. for member in resolve_mentions((str(event.payload["text"]),), room.members, default_all=False):
  311. if member.member_id != speaker_id:
  312. cited_at[member.member_id] = event.seq
  313. return tuple(
  314. member for member in room.members
  315. if member.member_id in cited_at and last_post_at.get(member.member_id, 0) <= cited_at[member.member_id])
  316. def _require_gateway_actor(actor: Mapping[str, Any], room: DiscussionRoom, message: str) -> None:
  317. if actor.get("kind") != "gateway" or actor.get("id") != room.gateway_id:
  318. raise DiscussionValidationError(message)
  319. def _member_by_id(room: DiscussionRoom, member_id: Any) -> DiscussionMember:
  320. normalized = _identifier(member_id, label="member_id")
  321. if (member := next((m for m in room.members if m.member_id == normalized), None)) is None:
  322. raise DiscussionValidationError(f"unknown Discussion member '{normalized}'")
  323. return member
  324. def _validate_turn_coordinates(payload: Mapping[str, Any], room: DiscussionRoom) -> None:
  325. _member_by_id(room, payload.get("member_id"))
  326. _zero_based_int(payload.get("member_index"), label="member_index", maximum=MAX_DISCUSSION_MEMBERS - 1)
  327. # Lowering the scheduling budget must not invalidate already-published higher rounds.
  328. _bounded_int(payload.get("round_index"), message="round_index must be a non-negative integer")
  329. for field in ("thread_id", "task_id", "turn_id", "discussion_event_id"):
  330. _identifier(payload.get(field), label=field)
  331. # -- per-kind event payload validators (dispatched by _validate_event) ---------
  332. # Each takes (kind, payload, actor, room) and returns the payload to record.
  333. def _validate_user_event(kind: str, payload: Payload, actor: Payload, room: DiscussionRoom) -> Payload:
  334. payload = validate_user_payload(payload)
  335. if actor.get("kind") != "user":
  336. raise DiscussionValidationError("message.user requires a user actor")
  337. return payload
  338. def _validate_member_message(kind: str, payload: Payload, actor: Payload, room: DiscussionRoom) -> Payload:
  339. _exact_fields(payload, label="message.member payload", required=_MEMBER_MESSAGE_FIELDS,
  340. optional={"attachments", "recipient_member_ids"})
  341. payload = dict(payload)
  342. if "attachments" in payload:
  343. payload["attachments"] = _message_manifest(payload["attachments"])
  344. if "recipient_member_ids" in payload:
  345. recipients = payload["recipient_member_ids"]
  346. if not isinstance(recipients, list) or not recipients:
  347. raise DiscussionValidationError("recipient_member_ids must be a non-empty list")
  348. recipients = [_member_by_id(room, recipient).member_id for recipient in recipients]
  349. if len(set(recipients)) != len(recipients):
  350. raise DiscussionValidationError("recipient_member_ids must be unique")
  351. payload["recipient_member_ids"] = recipients
  352. _validate_turn_coordinates(payload, room)
  353. if not isinstance(text := payload.get("text"), str) or not text.strip() or is_pass_text(text):
  354. raise DiscussionValidationError("message.member text must be a non-pass string")
  355. member = _member_by_id(room, payload.get("member_id"))
  356. expected = {**_member_actor(member, display_name=False), "connection_id": _peer_id(member)}
  357. if any(actor.get(key) != value for key, value in expected.items()):
  358. raise DiscussionValidationError("message.member actor does not match roster")
  359. return payload
  360. def _validate_terminal_event(kind: str, payload: Payload, actor: Payload, room: DiscussionRoom) -> Payload:
  361. _exact_fields(
  362. payload, label=f"{kind} payload", required=_TERMINAL_FIELDS[kind],
  363. optional=_TERMINAL_OPTIONAL_FIELDS.get(kind, frozenset()))
  364. _validate_turn_coordinates(payload, room)
  365. _positive_int(payload.get("seen_through_seq"), label="seen_through_seq")
  366. if actor.get("connection_id") is not None:
  367. raise DiscussionValidationError(f"{kind} requires a gateway actor")
  368. _require_gateway_actor(actor, room, f"{kind} requires a gateway actor")
  369. if kind == "turn.settled":
  370. if not isinstance(payload.get("passed"), bool):
  371. raise DiscussionValidationError("turn.settled passed must be a boolean")
  372. message_event_id = payload.get("message_event_id")
  373. if not payload["passed"]:
  374. _identifier(message_event_id, label="message_event_id")
  375. elif message_event_id is not None:
  376. raise DiscussionValidationError("a passed turn cannot reference a member message")
  377. return payload
  378. field = "error" if kind == "turn.failed" else "reason"
  379. if not isinstance(payload.get(field), str) or not payload[field].strip():
  380. raise DiscussionValidationError(f"{kind} {field} must be non-empty")
  381. if kind == "turn.deferred":
  382. _positive_int(payload.get("execution_generation"), label="execution_generation")
  383. if kind == "turn.failed" and "reason_code" in payload and payload["reason_code"] not in _all_failure_reasons():
  384. raise DiscussionValidationError("turn.failed reason_code must use the shared failure vocabulary")
  385. return payload
  386. def _validate_gateway_event(kind: str, payload: Payload, actor: Payload, room: DiscussionRoom) -> Payload:
  387. fields, identifier_fields = _GATEWAY_EVENT_FIELDS[kind]
  388. _exact_fields(payload, label=f"{kind} payload", required=fields)
  389. if kind == "room.activity" and payload.get("status") not in {"settled", "bounded"}:
  390. raise DiscussionValidationError("invalid room.activity status")
  391. for field in identifier_fields:
  392. _identifier(payload.get(field), label=field)
  393. _require_gateway_actor(actor, room, f"{kind} requires the room gateway")
  394. return payload
  395. _EVENT_VALIDATORS = {
  396. "message.user": _validate_user_event, "message.member": _validate_member_message,
  397. **dict.fromkeys(_TERMINAL_EVENT_KINDS, _validate_terminal_event),
  398. **dict.fromkeys(_GATEWAY_EVENT_FIELDS, _validate_gateway_event),
  399. lead_routing.ASSIGNMENT_EVENT_KIND: lead_routing.validate_assignment_event,
  400. router.ROUTED_EVENT_KIND: router.validate_routed_event, router.CONTINUED_EVENT_KIND: router.validate_continued_event}
  401. def _validate_event(raw: Any, *, room: DiscussionRoom, previous_seq: int) -> _ValidatedEvent:
  402. if not isinstance(raw, Mapping):
  403. raise DiscussionValidationError("room event must be an object")
  404. if raw.get("room_id") != room.room_id:
  405. raise DiscussionValidationError("room event belongs to a different room")
  406. if (seq := _positive_int(raw.get("seq"), label="event seq")) <= previous_seq:
  407. raise DiscussionValidationError("room events must be in strict sequence order")
  408. event_id = _identifier(raw.get("event_id"), label="event_id")
  409. kind, actor, payload = raw.get("kind"), raw.get("actor"), raw.get("payload")
  410. for value, expected, message in (
  411. (kind, str, "event kind must be a string"), (actor, Mapping, "event actor must be an object"),
  412. (payload, Mapping, "event payload must be an object")):
  413. if not isinstance(value, expected):
  414. raise DiscussionValidationError(message)
  415. if kind in _EPOCH_STAMPED_KINDS and raw.get("authority_epoch") != room.authority_epoch:
  416. raise DiscussionValidationError(f"{kind} authority epoch does not match the room")
  417. if (validator := _EVENT_VALIDATORS.get(kind)) is not None:
  418. payload = validator(kind, payload, actor, room)
  419. return _ValidatedEvent(raw=raw, seq=seq, event_id=event_id, kind=kind, actor=actor, payload=payload)
  420. def _validated_events(events: Sequence[Mapping[str, Any]], *, room: DiscussionRoom) -> tuple[_ValidatedEvent, ...]:
  421. validated: list[_ValidatedEvent] = []
  422. event_ids: set[str] = set()
  423. for raw in events:
  424. event = _validate_event(raw, room=room, previous_seq=validated[-1].seq if validated else 0)
  425. if event.event_id in event_ids:
  426. raise DiscussionValidationError("room event ids must be unique")
  427. validated.append(event)
  428. event_ids.add(event.event_id)
  429. return tuple(validated)
  430. def derive_member_watermarks(
  431. room_value: Any, events: Sequence[Mapping[str, Any]], *, local_profiles: Iterable[str]
  432. ) -> dict[tuple[str, str], int]:
  433. """Derive ``(thread_id, member_id)`` watermarks from terminal events."""
  434. return _derive_member_watermarks(
  435. _validated_events(events, room=validate_room(room_value, local_profiles=local_profiles)))
  436. def _derive_member_watermarks(events: Sequence[_ValidatedEvent]) -> dict[tuple[str, str], int]:
  437. messages_by_id = {event.event_id: event for event in events if event.kind == "message.member"}
  438. terminal_by_task: dict[str, _ValidatedEvent] = {}
  439. watermarks: dict[tuple[str, str], int] = {}
  440. for event in events:
  441. if event.kind not in _TERMINAL_EVENT_KINDS:
  442. continue
  443. task_id = str(event.payload["task_id"])
  444. if (previous := terminal_by_task.get(task_id)) is not None:
  445. if previous.kind != "turn.deferred":
  446. raise DiscussionValidationError(f"task '{task_id}' has more than one terminal room event")
  447. if event.kind == "turn.deferred" and int(
  448. event.payload["execution_generation"]) <= int(previous.payload["execution_generation"]):
  449. raise DiscussionValidationError(f"task '{task_id}' deferral generation did not advance")
  450. terminal_by_task[task_id] = event
  451. key = (str(event.payload["thread_id"]), str(event.payload["member_id"]))
  452. watermark = int(event.payload["seen_through_seq"])
  453. if event.kind == "turn.settled" and not event.payload["passed"]:
  454. message = messages_by_id.get(str(event.payload["message_event_id"]))
  455. if message is None or any(
  456. message.payload.get(f) != event.payload.get(f) for f in ("task_id", "member_id", "thread_id")):
  457. raise DiscussionValidationError("turn.settled references no matching member message")
  458. discussion_seq = next((candidate.seq for candidate in events
  459. if candidate.event_id == event.payload["discussion_event_id"]), None)
  460. if discussion_seq is None:
  461. raise DiscussionValidationError("turn.settled references no matching user discussion")
  462. if watermark >= discussion_seq:
  463. watermark = max(watermark, message.seq)
  464. watermarks[key] = max(watermarks.get(key, 0), watermark)
  465. return watermarks
  466. def _member_digest(member: DiscussionMember) -> str:
  467. target = compact_json(member.target or {"kind": "local", "profile": member.profile}, ensure_ascii=False)
  468. return hashlib.sha256(f"{member.member_id}\0{member.profile}\0{member.handle}\0{target}".encode()).hexdigest()[:24]
  469. def _rotate(members: Sequence[DiscussionMember], round_index: int) -> tuple[DiscussionMember, ...]:
  470. shift = round_index % len(members) if members else 0
  471. return tuple((*members[shift:], *members[:shift]))
  472. def _scheduled_job(event: _ValidatedEvent | None) -> str | None:
  473. """The job label of a scheduler-authored ``message.user`` event, else None (the human wrote it)."""
  474. if event is None or event.kind != "message.user" or scheduled_post_kind(event.actor) is None:
  475. return None
  476. return str(event.actor.get("display_name") or event.actor.get("id"))
  477. def _format_message(event: _ValidatedEvent, room: DiscussionRoom) -> str:
  478. if event.kind == "message.user" and (job := _scheduled_job(event)) is None:
  479. return f"User (user): {event.payload['text']}"
  480. # Scheduled output is agent-written too (often a summary of fetched content), so it gets the same
  481. # control-frame relabel as a member reply; only the human's own lines stay verbatim.
  482. text = _MEMBER_CONTROL_FRAME_RE.sub(_MEMBER_CONTROL_FRAME_RELABEL, event.payload["text"])
  483. if event.kind == "message.user":
  484. return f'Scheduled job "{job}" (automated post, not the user): {text}'
  485. return f"@{_member_by_id(room, event.payload['member_id']).handle}: {text}"
  486. def _truncate_utf8_text(value: Any, *, max_bytes: int, suffix: str = "") -> str:
  487. text = str(value or "")
  488. if len(encoded := text.encode("utf-8")) <= max_bytes:
  489. return text
  490. # ``ignore`` drops only the incomplete trailing sequence of a cut valid-UTF-8 prefix.
  491. prefix = encoded[: max(0, max_bytes - len(suffix.encode("utf-8")))].decode("utf-8", "ignore")
  492. return prefix + suffix if prefix else suffix.strip()
  493. def _context_lines(context: Mapping[str, str] | None) -> list[str]:
  494. """Room purpose and shared notes, rendered inside the user-role turn prompt (never the system prompt)."""
  495. lines: list[str] = []
  496. if context and context.get("purpose"):
  497. lines.append(f"Room purpose (set by the user): {context['purpose']}")
  498. if context and context.get("notes"):
  499. lines += ["Room notes (shared with every member; the user keeps them in room settings):",
  500. *(f" {line}" for line in context["notes"].splitlines())]
  501. return [*lines, ""] if lines else []
  502. def _build_prompt(
  503. *, room: DiscussionRoom, member: DiscussionMember, messages: Sequence[_ValidatedEvent], watermark: int,
  504. seen_through_seq: int, reply_required: bool = False, context: Mapping[str, str] | None = None,
  505. addressed_by_job: str | None = None, assigned_by: DiscussionMember | None = None, routed: bool = False) -> str:
  506. delta = [event for event in messages if watermark < event.seq <= seen_through_seq][- MAX_DISCUSSION_DELTA_LINES:]
  507. peers = ", ".join(f"@{candidate.handle}" for candidate in room.members if candidate.member_id != member.member_id)
  508. opening = [
  509. f'[Discussion: "{room.name}"] You are @{member.handle}, one participant '
  510. f"with {peers or 'no other members'} and the user.", "", *_context_lines(context),
  511. "New messages in this thread since your last turn (oldest first):"]
  512. addressed = (f"- The room lead @{assigned_by.handle} gave the user's message to you." if assigned_by
  513. else f'- The scheduled job "{addressed_by_job}" addressed you.' if addressed_by_job
  514. else "- The room picked you to answer the user's message." if routed
  515. else "- The user directly addressed you.")
  516. participation = [
  517. f"{addressed} Reply with your answer, result, or concrete blocker.",
  518. '- Do not return "(pass)". If you cannot proceed, explain why and what you need from the user.',
  519. ] if reply_required or assigned_by or routed else [
  520. "- Reply with one conversational message only when you have something new worth adding.",
  521. '- If you have nothing new to add, reply with exactly "(pass)".']
  522. rules = [
  523. "", "Rules for this Discussion:", *participation,
  524. "- Mention a teammate by handle to pull them into the next round; do not repeat points already made.",
  525. "- Never reveal content from private conversations. Your reply is published verbatim."]
  526. fixed_bytes = len("\n".join([*opening, *rules]).encode("utf-8"))
  527. available = max(0, driver.MAX_PROMPT_BYTES - fixed_bytes - 1)
  528. selected: list[str] = []
  529. for event in reversed(delta):
  530. line = f" {_format_message(event, room)}"
  531. if (line_bytes := len(line.encode("utf-8")) + 1) > available:
  532. if not selected and available > 32:
  533. selected.append(_truncate_utf8_text(line, max_bytes=available))
  534. selected.append(" [Earlier content omitted to fit this turn.]")
  535. break
  536. selected.append(line)
  537. available -= line_bytes
  538. selected.reverse()
  539. if len((prompt := "\n".join([*opening, *selected, *rules])).encode("utf-8")) > driver.MAX_PROMPT_BYTES:
  540. raise DiscussionValidationError("Discussion prompt exceeds the driver limit")
  541. return prompt
  542. def _requires_direct_reply(
  543. room: DiscussionRoom, source: _ValidatedEvent | None, member: DiscussionMember, round_index: int,
  544. ) -> bool:
  545. # Only the user's initial address requires a reply. A later peer handoff may
  546. # legitimately pass after this member has already answered that user.
  547. return (round_index == 0 and source is not None and source.kind == "message.user"
  548. and member in resolve_mentions((str(source.payload["text"]),), room.members, default_all=False))
  549. def _make_task_plan(
  550. *, room: DiscussionRoom, discussion_event: _ValidatedEvent, member: DiscussionMember, member_index: int,
  551. round_index: int, seen_through_seq: int, prompt: str,
  552. input_context: Mapping[str, Any] | None = None,
  553. attachments: Sequence[Mapping[str, Any]] = (), lead_routing: bool = False) -> DiscussionTaskPlan:
  554. turn_id = f"d{discussion_event.seq}.r{round_index}.p{member_index}.s{seen_through_seq}.m{_member_digest(member)}"
  555. if attachments:
  556. attachments = driver.validate_bound_task_manifest(list(attachments))
  557. # A routing turn's id omits its prompt: the planner re-mints it on every replay to find its receipt, and
  558. # the prompt names the room and roster, which a rename or display-name edit changes after the turn ran.
  559. seed = compact_json({
  560. "discussion_event_id": discussion_event.event_id, "member_id": member.member_id, "member_index": member_index,
  561. **({} if lead_routing else {"prompt_sha256": hashlib.sha256(prompt.encode("utf-8")).hexdigest()}),
  562. "room_id": room.room_id,
  563. "round_index": round_index, "seen_through_seq": seen_through_seq, "source_event_seq": discussion_event.seq,
  564. "thread_id": discussion_event.payload["thread_id"],
  565. **({"input_context": input_context} if input_context is not None else {}),
  566. **({"attachments": attachments} if attachments else {}),
  567. **({"lead_routing": True} if lead_routing else {})})
  568. identity = driver.TaskIdentity(
  569. room_id=room.room_id, task_id=f"dtask:{hashlib.sha256(seed.encode('utf-8')).hexdigest()[:48]}",
  570. thread_id=str(discussion_event.payload["thread_id"]), turn_id=turn_id)
  571. payload = {
  572. "target_member_id": member.member_id, "target_profile": member.profile, "prompt": prompt,
  573. "source_event_seq": discussion_event.seq}
  574. if attachments:
  575. payload["attachments"] = list(attachments)
  576. if input_context is not None:
  577. payload["input_context"] = dict(input_context)
  578. if lead_routing:
  579. payload["lead_routing"] = True
  580. return DiscussionTaskPlan(
  581. identity, payload, discussion_event.event_id, member, member_index, round_index, seen_through_seq)
  582. def _pending_discussion(validated: Sequence[_ValidatedEvent]) -> _ValidatedEvent | None:
  583. """Oldest latest-per-thread user message not stopped and not yet completed. A ``room.continued``
  584. reopens a discussion its earlier activity completed (Continue at the cap)."""
  585. stopped_through_seq = max((event.seq for event in validated if event.kind == "room.stop_requested"), default=0)
  586. continued_at = router.continued_through(validated)
  587. completed_discussion_ids = {
  588. str(event.payload["discussion_event_id"]) for event in validated
  589. if event.kind == "room.activity" and event.payload.get("status") in {"settled", "bounded"}
  590. and event.seq > continued_at.get(str(event.payload["discussion_event_id"]), 0)}
  591. latest_by_thread = {
  592. str(event.payload["thread_id"]): event for event in validated if event.kind == "message.user"}
  593. return next((
  594. event for event in sorted(latest_by_thread.values(), key=lambda item: item.seq)
  595. if event.seq > stopped_through_seq and event.event_id not in completed_discussion_ids), None)
  596. def _thread_messages(
  597. validated: Sequence[_ValidatedEvent], discussion: _ValidatedEvent
  598. ) -> tuple[tuple[_ValidatedEvent, ...], tuple[_ValidatedEvent, ...], tuple[_ValidatedEvent, ...]]:
  599. """Return (thread messages, messages since the discussion, this discussion's member messages)."""
  600. thread_id = str(discussion.payload["thread_id"])
  601. committed_member_message_ids = {
  602. str(event.payload["message_event_id"]) for event in validated
  603. if event.kind == "turn.settled" and event.payload.get("message_event_id") is not None}
  604. # Publication writes the visible member message before the terminal event.
  605. # A crash in that gap leaves the message in the log, but it is not committed
  606. # policy input yet: ignoring it reproduces the original task coordinates so
  607. # the caller can inspect the terminal driver row and finish publication.
  608. thread_messages = tuple(
  609. event for event in validated
  610. if event.payload.get("thread_id") == thread_id and (
  611. event.kind == "message.user"
  612. or (event.kind == "message.member" and event.event_id in committed_member_message_ids)))
  613. return thread_messages, tuple(event for event in thread_messages if event.seq >= discussion.seq), tuple(
  614. event for event in thread_messages
  615. if event.kind == "message.member" and event.payload.get("discussion_event_id") == discussion.event_id)
  616. def _effective_watermarks(
  617. validated: Sequence[_ValidatedEvent], initial_watermarks: Mapping[tuple[str, str], int] | None
  618. ) -> dict[tuple[str, str], int]:
  619. watermarks = {
  620. (str(thread_id), str(member_id)): int(value)
  621. for (thread_id, member_id), value in (initial_watermarks or {}).items() if int(value) >= 0}
  622. for key, value in _derive_member_watermarks(validated).items():
  623. watermarks[key] = max(watermarks.get(key, 0), value)
  624. return watermarks
  625. def _event_attachments(event: _ValidatedEvent, member: DiscussionMember) -> list[dict[str, Any]]:
  626. if event.kind == "message.member":
  627. if event.payload["member_id"] == member.member_id:
  628. return []
  629. recipients = event.payload.get("recipient_member_ids")
  630. if recipients is not None and member.member_id not in recipients:
  631. return []
  632. return [{**attachment, "event_id": event.event_id} for attachment in event.payload.get("attachments", [])]
  633. def _bounded_task_delta(messages: Sequence[_ValidatedEvent], *, watermark: int,
  634. member: DiscussionMember) -> tuple[list[_ValidatedEvent], list[dict[str, Any]]]:
  635. from gateway.hosted_room_attachments import MAX_TASK_ATTACHMENTS, MAX_TASK_ATTACHMENT_BYTES
  636. selected: list[_ValidatedEvent] = []
  637. attachments: list[dict[str, Any]] = []
  638. size = 0
  639. for event in messages:
  640. if event.seq <= watermark:
  641. continue
  642. entries = _event_attachments(event, member)
  643. next_size = size + sum(item["size"] for item in entries)
  644. if len(attachments) + len(entries) > MAX_TASK_ATTACHMENTS or next_size > MAX_TASK_ATTACHMENT_BYTES:
  645. break # Each validated message fits; consume only whole event prefixes.
  646. selected.append(event)
  647. attachments.extend(entries)
  648. size = next_size
  649. return selected, attachments
  650. def _first_round_responders(discussion: _ValidatedEvent, room: DiscussionRoom) -> tuple[DiscussionMember, ...]:
  651. """The human's message with no mention addresses everyone. A scheduled post is only a message in the
  652. room: it pulls in exactly the members it @mentions, and a failure notice pulls in nobody."""
  653. scheduled = scheduled_post_kind(discussion.actor)
  654. if scheduled == "notice":
  655. return ()
  656. return resolve_mentions((str(discussion.payload["text"]),), room.members, default_all=scheduled is None)
  657. @dataclass(frozen=True)
  658. class _LeadRound:
  659. """Lead routing for one discussion: the routing turn still to run, or who the lead gave it to."""
  660. task: DiscussionTaskPlan | None
  661. responders: tuple[DiscussionMember, ...]
  662. lead: DiscussionMember
  663. routing_task_id: str
  664. def _lead_round(
  665. room: DiscussionRoom, discussion: _ValidatedEvent, validated: Sequence[_ValidatedEvent],
  666. context: Mapping[str, str]) -> _LeadRound | None:
  667. """None unless the room routes through a lead and this message goes to it (``hosted_room_lead``)."""
  668. lead = lead_routing.lead_member(room, context)
  669. if lead is None or not lead_routing.routes_through_lead(discussion, room, validated):
  670. return None
  671. prompt = lead_routing.routing_prompt(
  672. room=room, lead=lead, discussion=discussion, context_lines=_context_lines(context))
  673. task = _make_task_plan(room=room, discussion_event=discussion, member=lead, member_index=0, round_index=0,
  674. seen_through_seq=discussion.seq - 1, prompt=prompt, lead_routing=True)
  675. chosen = lead_routing.first_round_members(room, lead, validated, discussion.event_id, task.identity.task_id)
  676. return _LeadRound(task if chosen is None else None, chosen or (), lead, task.identity.task_id)
  677. def plan_next_task(
  678. room_value: Any, events: Sequence[Mapping[str, Any]], *, local_profiles: Iterable[str],
  679. initial_watermarks: Mapping[tuple[str, str], int] | None = None,
  680. freeze_input_context: bool = False,
  681. limits: DiscussionLimits = DiscussionLimits(),
  682. room_context: Mapping[str, Any] | None = None,
  683. ) -> DiscussionDecision:
  684. """Replay the complete room log and return at most one next member task. ``room_context`` is the
  685. room settings in force when the pending discussion opened (``hosted_room_context.room_context``)."""
  686. room = validate_room(room_value, local_profiles=local_profiles)
  687. try:
  688. context = validate_context(**{key: str((room_context or {}).get(key) or default) for key, default in (
  689. ("purpose", ""), ("notes", ""), ("routing", "everyone"), ("lead_member_id", ""))})
  690. except ValueError as exc:
  691. raise DiscussionValidationError(str(exc)) from exc
  692. validated = _validated_events(events, room=room)
  693. if (discussion := _pending_discussion(validated)) is None:
  694. return DiscussionDecision(status="idle", reason="no_pending_user_event")
  695. thread_id = str(discussion.payload["thread_id"])
  696. continues = router.continue_count(validated, discussion.event_id)
  697. # Each Continue grants one more full budget of rounds and messages for the same discussion.
  698. max_rounds, max_messages = limits.max_rounds * (continues + 1), limits.max_messages * (continues + 1)
  699. decide = partial(
  700. DiscussionDecision, discussion_event_id=discussion.event_id, source_event_seq=discussion.seq,
  701. thread_id=thread_id, continues=continues)
  702. thread_messages, discussion_messages, member_messages = _thread_messages(validated, discussion)
  703. if len(member_messages) >= max_messages:
  704. return decide("bounded", "max_messages")
  705. routed = router.routed_responders(room, discussion, validated, context)
  706. if routed is router.ROUTE_PENDING:
  707. # The router's answer is recorded as ``room.routed`` before any turn is planned, so replay never re-asks.
  708. return decide("route", "router_pending")
  709. if (lead_round := _lead_round(room, discussion, validated, context)) is not None and lead_round.task:
  710. return decide("task", "lead_routing", task=lead_round.task)
  711. # The lead's routing receipt is not its round-0 turn: a lead that gave the message to itself still answers.
  712. routing_task_id = lead_round.routing_task_id if lead_round else None
  713. terminals = {
  714. (int(event.payload["round_index"]), str(event.payload["member_id"])) for event in validated
  715. if event.kind in _TERMINAL_EVENT_KINDS and event.payload.get("discussion_event_id") == discussion.event_id
  716. and event.payload.get("task_id") != routing_task_id}
  717. watermarks = _effective_watermarks(validated, initial_watermarks)
  718. resume_round = router.resume_round(validated, discussion.event_id, member_messages)
  719. for round_index in range(max_rounds):
  720. # The user's message selects the first round, with no mention meaning
  721. # everyone. Later rounds are opt-in: only a peer explicitly cited by a
  722. # Bot and not heard from afterward gets another turn. Every member's
  723. # watermark remains intact, so a peer cited later still receives the
  724. # complete bounded transcript delta without consuming turns meanwhile.
  725. responders = (
  726. (lead_round.responders if lead_round else routed if routed is not None
  727. else _first_round_responders(discussion, room)) if round_index == 0
  728. else _unaddressed_member_mentions(discussion_messages, room))
  729. if not responders and round_index == resume_round:
  730. # The round after the pause: with nobody cited, the whole room picks the discussion back up.
  731. responders = room.members
  732. for member_index, member in enumerate(_rotate(responders, round_index)):
  733. watermark = watermarks.get((thread_id, member.member_id), 0)
  734. delta, attachments = _bounded_task_delta(thread_messages, watermark=watermark, member=member)
  735. if not delta or ((round_index, member.member_id) in terminals and not attachments):
  736. continue
  737. seen_through_seq = delta[-1].seq
  738. prompt = _build_prompt(
  739. room=room, member=member, messages=thread_messages, watermark=watermark,
  740. seen_through_seq=seen_through_seq, context=context, addressed_by_job=_scheduled_job(discussion),
  741. reply_required=_requires_direct_reply(room, discussion, member, round_index),
  742. assigned_by=lead_round.lead if lead_round and round_index == 0 and member != lead_round.lead else None,
  743. routed=round_index == 0 and routed is not None and len(routed) < len(room.members))
  744. return decide("task", "member_turn", task=_make_task_plan(
  745. room=room, discussion_event=discussion, member=member, member_index=member_index,
  746. round_index=round_index, seen_through_seq=seen_through_seq, prompt=prompt, attachments=attachments,
  747. input_context=(validate_task_input({"watermark": watermark, "event_seqs": [event.seq for event in delta]})
  748. if freeze_input_context or attachments else None)))
  749. if not any(int(event.payload["round_index"]) == round_index for event in member_messages):
  750. return decide("settled", "silent_round")
  751. if round_index == max_rounds - 1:
  752. return decide("bounded", "max_rounds")
  753. raise AssertionError("bounded Discussion loop exhausted unexpectedly")
  754. def _reconstructed_lead_routing(payload: Mapping[str, Any], match: re.Match[str], source_event_seq: int) -> bool:
  755. """A persisted routing turn keeps the only coordinates ``_lead_round`` mints: round 0, position 0,
  756. seeing through the message before its own, with no frozen input or files."""
  757. if "lead_routing" not in payload:
  758. return False
  759. if payload["lead_routing"] is not True or (match.group("round"), match.group("position")) != ("0", "0") or (
  760. int(match.group("seen")) != source_event_seq - 1 or {"input_context", "attachments"} & set(payload)):
  761. raise DiscussionReconstructionError("lead routing task does not match its turn_id")
  762. return True
  763. def reconstruct_task_plan(
  764. room_value: Any, events: Sequence[Mapping[str, Any]], task: Mapping[str, Any], *, local_profiles: Iterable[str]
  765. ) -> DiscussionTaskPlan:
  766. """Reconstruct and verify one persisted driver task after a restart."""
  767. room = validate_room(room_value, local_profiles=local_profiles)
  768. validated = _validated_events(events, room=room)
  769. identity, payload = task.get("identity"), task.get("payload")
  770. if not isinstance(identity, driver.TaskIdentity) or not isinstance(payload, Mapping):
  771. raise DiscussionReconstructionError("driver task has no valid identity or payload")
  772. fields = frozenset(payload)
  773. if not driver._TASK_PAYLOAD_REQUIRED_FIELDS <= fields <= (
  774. driver._TASK_PAYLOAD_REQUIRED_FIELDS | driver._TASK_PAYLOAD_OPTIONAL_FIELDS):
  775. raise DiscussionReconstructionError("driver task payload shape changed")
  776. if (match := _TURN_ID_RE.fullmatch(identity.turn_id)) is None:
  777. raise DiscussionReconstructionError("turn_id is not a Discussion coordinate")
  778. source_event_seq = int(match.group("source"))
  779. if payload.get("source_event_seq") != source_event_seq:
  780. raise DiscussionReconstructionError("task source event does not match turn_id")
  781. discussion = next((e for e in validated if e.seq == source_event_seq and e.kind == "message.user"), None)
  782. if discussion is None:
  783. raise DiscussionReconstructionError("task source user event is missing")
  784. if identity.room_id != room.room_id or identity.thread_id != discussion.payload["thread_id"]:
  785. raise DiscussionReconstructionError("task identity does not match its room thread")
  786. profile, target_member_id = payload.get("target_profile"), payload.get("target_member_id")
  787. member = next((
  788. m for m in room.members
  789. if m.profile == profile and (target_member_id is None or m.member_id == target_member_id)), None)
  790. if member is None or _member_digest(member) != match.group("member"):
  791. raise DiscussionReconstructionError("task target member does not match turn_id")
  792. if not isinstance(prompt := payload.get("prompt"), str) or not prompt.strip():
  793. raise DiscussionReconstructionError("task prompt is missing")
  794. if len(prompt.encode("utf-8")) > driver.MAX_PROMPT_BYTES:
  795. raise DiscussionReconstructionError("task prompt exceeds the driver limit")
  796. input_context = None
  797. if "input_context" in payload:
  798. try:
  799. input_context = validate_task_input(payload["input_context"])
  800. except ValueError as exc:
  801. raise DiscussionReconstructionError(str(exc)) from exc
  802. if input_context["event_seqs"][-1] != int(match.group("seen")):
  803. raise DiscussionReconstructionError("task input does not match turn_id")
  804. message_seqs = {event.seq for event in validated
  805. if event.kind in {"message.user", "message.member"}
  806. and event.payload.get("thread_id") == identity.thread_id}
  807. if any(seq not in message_seqs for seq in input_context["event_seqs"]):
  808. raise DiscussionReconstructionError("task input message is missing")
  809. attachments: list[dict[str, Any]] = []
  810. if "attachments" in payload:
  811. if input_context is None:
  812. raise DiscussionReconstructionError("attachment task requires frozen input_context")
  813. by_seq = {event.seq: event for event in validated}
  814. attachments = [item for seq in input_context["event_seqs"]
  815. for item in _event_attachments(by_seq[seq], member)]
  816. lead_routing = _reconstructed_lead_routing(payload, match, source_event_seq)
  817. reconstructed = _make_task_plan(
  818. room=room, discussion_event=discussion, member=member, member_index=int(match.group("position")),
  819. round_index=int(match.group("round")), seen_through_seq=int(match.group("seen")), prompt=prompt,
  820. input_context=input_context, attachments=attachments, lead_routing=lead_routing)
  821. if reconstructed.identity != identity or dict(reconstructed.payload) != dict(payload):
  822. raise DiscussionReconstructionError("driver task failed deterministic reconstruction")
  823. return reconstructed
  824. def _turn_coordinates(task: DiscussionTaskPlan) -> dict[str, Any]:
  825. """The coordinate fields every member message and terminal event carries."""
  826. return {
  827. "discussion_event_id": task.discussion_event_id, "member_id": task.member.member_id,
  828. "member_index": task.member_index, "round_index": task.round_index, "task_id": task.identity.task_id,
  829. "thread_id": task.identity.thread_id, "turn_id": task.identity.turn_id}
  830. def _terminal_text(result: Any, *, field: str, fallback: str) -> str:
  831. if isinstance(result, Mapping):
  832. result = result.get(field) if field != "error" or result.get("error") is not None else result.get("text")
  833. return str(result or "").strip() or fallback
  834. # -- per-status terminal payload builders (dispatched by plan_publication) -----
  835. # Each returns (extra terminal payload fields, visible effects to publish first).
  836. Effects = tuple[dict[str, Any], list[EventPlan]]
  837. def _settled_effects(
  838. result: Any, *, task: DiscussionTaskPlan, room: DiscussionRoom, message_event_id: str, **_: Any) -> Effects:
  839. text = _truncate_utf8_text(
  840. _terminal_text(result, field="text", fallback=""), max_bytes=MAX_MEMBER_TEXT_BYTES,
  841. suffix=_TRUNCATED_REPLY_NOTICE)
  842. if is_pass_text(text):
  843. return {"message_event_id": None, "passed": True}, []
  844. return {"message_event_id": message_event_id, "passed": False}, [EventPlan(
  845. event_id=message_event_id, kind="message.member", actor=_member_actor(task.member),
  846. payload={**_turn_coordinates(task), "text": text}, authority_gateway_id=room.gateway_id,
  847. authority_epoch=room.authority_epoch)]
  848. def _failed_effects(result: Any, **_: Any) -> Effects:
  849. error_text = _terminal_text(result, field="error", fallback="member turn failed")
  850. from tools.bot_failure_reasons import classify_agent_error
  851. supplied_reason = (
  852. str(result.get("reason_code") or result.get("reason") or "").strip() if isinstance(result, Mapping) else "")
  853. reason_code = supplied_reason if supplied_reason in _all_failure_reasons() else classify_agent_error(error_text)
  854. return {"error": error_text, "reason_code": reason_code}, []
  855. def _cancelled_effects(result: Any, *, newer_same_thread: bool, **_: Any) -> Effects:
  856. if newer_same_thread:
  857. return {"reason": "superseded_by_newer_user_event"}, []
  858. return {"reason": _terminal_text(result, field="reason", fallback="member turn cancelled")}, []
  859. def _deferred_effects(result: Any, *, execution_generation: int | None, **_: Any) -> Effects:
  860. reason = _terminal_text(result, field="reason", fallback="member_unavailable")
  861. return {"execution_generation": execution_generation, "reason": reason}, []
  862. _TERMINAL_EFFECTS = {
  863. "settled": _settled_effects, "failed": _failed_effects, "cancelled": _cancelled_effects,
  864. "deferred": _deferred_effects}
  865. def plan_publication(
  866. room_value: Any, events: Sequence[Mapping[str, Any]], task: DiscussionTaskPlan, *, status: TerminalKind,
  867. result: Any = None, execution_generation: int | None = None, local_profiles: Iterable[str]) -> PublicationPlan:
  868. """Plan idempotent room effects for one terminal driver task.
  869. A newer user event in the same thread supersedes a late result: the task stays terminal in driver state,
  870. but only a deterministic cancellation is published so stale prose and its watermark cannot hide it.
  871. """
  872. room = validate_room(room_value, local_profiles=local_profiles)
  873. validated = _validated_events(events, room=room)
  874. for failed, message in (
  875. (task.identity.room_id != room.room_id, "task belongs to a different room"),
  876. (task.member not in room.members, "task member is not in the frozen roster"),
  877. (status not in _TERMINAL_EFFECTS, "invalid terminal publication status")):
  878. if failed:
  879. raise DiscussionValidationError(message)
  880. if status == "deferred":
  881. _bounded_int(execution_generation, message="deferred publication requires an execution generation", low=1)
  882. newer_same_thread = any(
  883. event.kind == "message.user" and event.seq > int(task.payload["source_event_seq"])
  884. and event.payload.get("thread_id") == task.identity.thread_id for event in validated)
  885. effective_status: TerminalKind = ("cancelled" if newer_same_thread and status != "deferred" else status)
  886. source = next((event for event in validated if event.event_id == task.discussion_event_id), None)
  887. if (effective_status == "settled" and _requires_direct_reply(room, source, task.member, task.round_index)
  888. and is_pass_text(_terminal_text(result, field="text", fallback=""))):
  889. # The execution completed, but did not answer the user. Publish that
  890. # failure from the durable receipt without replaying any tools or model calls.
  891. effective_status = "failed"
  892. result = {"error": f"@{task.member.handle} was directly addressed but returned no visible reply."}
  893. digest = task.identity.task_id.removeprefix("dtask:")
  894. terminal_event_id = (
  895. f"ddeferred:{digest}:g{execution_generation}" if effective_status == "deferred" else f"dterminal:{digest}")
  896. routing = lead_routing.is_routing_task(task)
  897. # A routing answer is never published as a reply: it becomes the room.assignment ahead of the receipt.
  898. extra, effects = _TERMINAL_EFFECTS[effective_status](
  899. "(pass)" if routing and effective_status == "settled" else result, task=task, room=room, message_event_id=f"dmessage:{digest}",
  900. newer_same_thread=newer_same_thread, execution_generation=execution_generation)
  901. if routing:
  902. effects = lead_routing.assignment_effect(result, task=task, room=room, status=effective_status) + effects
  903. terminal_kind = f"turn.{effective_status}"
  904. effects.append(EventPlan(
  905. event_id=terminal_event_id, kind=terminal_kind, actor={"kind": "gateway", "id": room.gateway_id},
  906. payload={**_turn_coordinates(task), "seen_through_seq": task.seen_through_seq, **extra},
  907. authority_gateway_id=room.gateway_id, authority_epoch=room.authority_epoch))
  908. return PublicationPlan(task_id=task.identity.task_id, terminal_kind=terminal_kind, events=tuple(effects))