Skip to content

Self-improving AI Employees for everyone

feat(chat): edit, try again and switch versions, with memory that follows

trohitg25f7a283c0b0
diff --git a/server/config/chat_defaults.json b/server/config/chat_defaults.json
index 7ca66657..718c2f82 100644
--- a/server/config/chat_defaults.json
+++ b/server/config/chat_defaults.json
@@ -15,5 +15,9 @@
},
"steps": {
"max_per_run": 100
+ },
+ "branches": {
+ "max_snapshots_per_session": 50,
+ "max_snapshot_bytes": 1048576
}
}
diff --git a/server/core/database.py b/server/core/database.py
index 7a26e363..6281a400 100644
--- a/server/core/database.py
+++ b/server/core/database.py
@@ -61,6 +61,8 @@ from models.approvals import ( # noqa: F401 - registers SQLModel tables
WorkflowRule,
)
from models.chat import ( # noqa: F401 - registers SQLModel tables
+ ChatBranchSnapshot,
+ ChatFeedback,
ChatNote,
ChatRun,
ChatRunPart,
@@ -71,6 +73,10 @@ from core.logging import get_logger
logger = get_logger(__name__)
+#: ``Database.append_chat_row``'s default: the new message follows the
+#: thread's active leaf.
+FOLLOW_LEAF: Any = object()
+
RuntimeMutationCallback = Callable[
[AsyncSession],
Union[Optional[Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]],
@@ -533,7 +539,7 @@ class Database:
"""Give older ``chat_runs`` and ``chat_threads`` tables the columns
added since."""
additions = {
- "chat_runs": {"stop_requested_at": "DATETIME"},
+ "chat_runs": {"stop_requested_at": "DATETIME", "context_cursors": "JSON DEFAULT '{}'"},
"chat_threads": {"next_source": "INTEGER NOT NULL DEFAULT 1"},
}
try:
@@ -1510,6 +1516,7 @@ class Database:
parts: Optional[Dict[str, Any]] = None,
attachments: Optional[List[Dict[str, Any]]] = None,
meta: Optional[Dict[str, Any]] = None,
+ after: Any = FOLLOW_LEAF,
) -> ChatMessage:
"""Append a message to the end of a session's shown path, inside the
caller's :meth:`reserved_session` (the caller commits).
@@ -1518,6 +1525,9 @@ class Database:
every message joins one chain: two writers at once would otherwise
both follow the same leaf and fork it, and a fork hides one branch. A
session written before threads existed follows its newest message.
+ ``after`` names the message it follows instead (None: it starts the
+ conversation), the way an edit goes beside the message it edits
+ (``services/chat/branches.py``).
"""
from uuid import uuid4
@@ -1534,6 +1544,8 @@ class Database:
session.add(thread)
else:
parent_uid = thread.active_leaf_uid
+ if after is not FOLLOW_LEAF:
+ parent_uid = after
row = ChatMessage(
session_id=session_id, role=role, message=message,
execution_id=execution_id,
@@ -1650,8 +1662,8 @@ class Database:
async def clear_chat_messages(self, session_id: str) -> int:
"""Clear a session's chat: its messages, and the runs, run parts,
- notes and thread state that belong to them. Returns the messages
- deleted."""
+ notes, branch snapshots, ratings and thread state that belong to
+ them. Returns the messages deleted."""
from sqlalchemy import delete as sa_delete
try:
@@ -1668,6 +1680,8 @@ class Database:
await session.execute(sa_delete(ChatRunPart).where(ChatRunPart.run_id.in_(run_ids)))
await session.execute(sa_delete(ChatRun).where(ChatRun.session_id == session_id))
await session.execute(sa_delete(ChatNote).where(ChatNote.session_id == session_id))
+ await session.execute(sa_delete(ChatBranchSnapshot).where(ChatBranchSnapshot.session_id == session_id))
+ await session.execute(sa_delete(ChatFeedback).where(ChatFeedback.session_id == session_id))
await session.execute(sa_delete(ChatThread).where(ChatThread.session_id == session_id))
await session.commit()
diff --git a/server/models/chat.py b/server/models/chat.py
index babfe362..97831892 100644
--- a/server/models/chat.py
+++ b/server/models/chat.py
@@ -17,8 +17,16 @@ agent_context_flow.md). A second message while one is live is refused with
``ChatRunPart`` collects what a run's tools produce for its reply (generated
UI, sources, artifacts, approvals), keyed so an activity retry writes the
same row again. ``ChatThread`` holds a session's active leaf: the message the
-shown path ends at, which branches will move, and its source counter.
+shown path ends at, which branches move, and its source counter.
``ChatNote`` holds what the employee should learn on its next turn.
+
+**Branches** (``services/chat/branches.py``). A run records, for each agent
+with a stored conversation that works for it, the conversation as it was
+when the run began (``context_cursors``: its length and a digest), so an
+edit or a retry can take the agent back to it. ``ChatBranchSnapshot`` keeps
+the conversations of a branch the owner moved away from, keyed by the leaf
+they left, so moving back restores them. ``ChatFeedback`` is the owner's
+rating of an answer.
"""
from __future__ import annotations
@@ -87,6 +95,10 @@ class ChatRun(SQLModel, table=True):
#: When the owner pressed Stop; the watchdog ends a run still stopping
#: ``runs.stop_grace_s`` later.
stop_requested_at: Optional[datetime] = Field(default=None, sa_column=Column(DateTime(timezone=True), nullable=True))
+ #: Per agent that worked for it with a stored conversation, that
+ #: conversation as the run began: ``{agent_node_id: {generation, length,
+ #: digest}}`` (the first time each agent was prepared in the run).
+ context_cursors: Dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON))
class ChatRunPart(SQLModel, table=True):
@@ -126,4 +138,42 @@ class ChatNote(SQLModel, table=True):
delivered_at: Optional[datetime] = Field(default=None, sa_column=Column(DateTime(timezone=True), nullable=True))
-__all__ = ["ChatNote", "ChatRun", "ChatRunPart", "ChatThread", "LIVE_STATES", "TERMINAL_STATES"]
+class ChatBranchSnapshot(SQLModel, table=True):
+ """An agent's conversation on a branch the owner moved away from, keyed
+ by the message that branch ended at (its leaf)."""
+
+ __tablename__ = "chat_branch_snapshots"
+ __table_args__ = (UniqueConstraint("session_id", "leaf_uid", "agent_node_id", name="uq_chat_branch_snapshots_key"),)
+
+ id: Optional[int] = Field(default=None, primary_key=True)
+ session_id: str = Field(index=True, max_length=255)
+ leaf_uid: str = Field(max_length=64)
+ agent_node_id: str = Field(max_length=255)
+ generation: int = Field(default=0)
+ messages: List[Dict[str, Any]] = Field(default_factory=list, sa_column=Column(JSON))
+ created_at: datetime = Field(default_factory=_utcnow, sa_column=Column(DateTime(timezone=True), nullable=False))
+
+
+class ChatFeedback(SQLModel, table=True):
+ """The owner's rating of an answer: ``up`` or ``down``."""
+
+ __tablename__ = "chat_feedback"
+ __table_args__ = (UniqueConstraint("session_id", "message_uid", name="uq_chat_feedback_message"),)
+
+ id: Optional[int] = Field(default=None, primary_key=True)
+ session_id: str = Field(index=True, max_length=255)
+ message_uid: str = Field(max_length=64)
+ value: str = Field(max_length=10)
+ updated_at: datetime = Field(default_factory=_utcnow, sa_column=Column(DateTime(timezone=True), nullable=False))
+
+
+__all__ = [
+ "ChatBranchSnapshot",
+ "ChatFeedback",
+ "ChatNote",
+ "ChatRun",
+ "ChatRunPart",
+ "ChatThread",
+ "LIVE_STATES",
+ "TERMINAL_STATES",
+]
diff --git a/server/services/agent_context/conversation.py b/server/services/agent_context/conversation.py
index 66f61e55..d8f06142 100644
--- a/server/services/agent_context/conversation.py
+++ b/server/services/agent_context/conversation.py
@@ -43,6 +43,13 @@ def _lock(workflow_id: str, generation: int, agent_node_id: str) -> asyncio.Lock
return lock
+def conversation_lock(workflow_id: str, generation: int, agent_node_id: str) -> asyncio.Lock:
+ """The lock :func:`save_conversation` holds for one conversation. Hold
+ it (``async with``) to rewrite the conversation outside this module,
+ as a chat branch move does (``services/chat/branches.py``)."""
+ return _lock(workflow_id, generation, agent_node_id)
+
+
async def load_conversation(
database: Any,
*,
@@ -284,6 +291,7 @@ __all__ = [
"UNANSWERED_TOOL_RESULT",
"clear_conversation",
"close_unanswered_tool_calls",
+ "conversation_lock",
"list_conversations",
"load_conversation",
"save_conversation",
diff --git a/server/services/chat/branches.py b/server/services/chat/branches.py
new file mode 100644
index 00000000..9fd5bba1
--- /dev/null
+++ b/server/services/chat/branches.py
@@ -0,0 +1,805 @@
+"""Branches of a chat: editing the owner's message, trying an answer again,
+and moving between versions (docs-internal/chat_protocol.md, "Branches").
+
+A session's messages form a tree: each row names the one before it
+(``parent_uid``), and the thread's active leaf (``chat_threads``) is where
+the shown path ends. An edit adds the edited message beside the original
+(same parent) and starts a run that answers it; a retry starts a new run for
+the same message, whose answer goes beside the old one; a switch moves the
+leaf into another version's branch, at the newest message on it. Only the
+path from the first message to the leaf is shown (``active_path``); the
+messages beside each one, with the same parent and role, are its versions
+(``sibling_ids``).
+
+**The employee's memory follows the path.** Each run records, per agent
+with a stored conversation that works for it, the conversation as the run
+began (``ChatRun.context_cursors``: its length and a digest without the
+stamps the store adds; ``record_cursor``). Leaving a branch saves the
+conversations of the agents that worked on the part being left under that
+branch's leaf (``chat_branch_snapshots``) and takes each back to where it
+stood before that part: the cursor of the first run on it that touched the
+agent, checked against the stored conversation. A conversation that no
+longer starts that way (it was summarized or cleared since) refuses the move
+(``cannot_rewind``). Moving back onto a branch restores its saved
+conversations; one no longer saved refuses the move (``branch_unavailable``).
+
+Every move runs in one reserved write transaction, under the conversation
+store's per-agent locks, after checking the thread's revision (a change made
+meanwhile refuses it, ``revision_conflict``) and that no run holds the lane
+(``run_in_progress``). Messages and runs from before the live generation
+cannot be moved (``older_generation``). After it commits, ``after_move``
+tells the Context panel about the conversations it changed, cancels the
+drafts the runs on the part left made that still wait, and leaves the
+employee a note about what those runs sent anyway.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from contextlib import AsyncExitStack
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Set, Tuple
+
+from sqlalchemy import delete, func
+from sqlmodel import select
+
+from core.logging import get_logger
+from models.agent_context import AgentConversation
+from models.chat import LIVE_STATES, TERMINAL_STATES, ChatBranchSnapshot, ChatRun, ChatThread
+from models.database import ChatMessage
+from services.chat.config import branches_setting
+
+logger = get_logger(__name__)
+
+#: Kinds of the owner's message that can be edited (not a button press, a
+#: report or a notice).
+EDITABLE_KINDS = frozenset({"text"})
+
+
+class BranchRefused(Exception):
+ """A change to the conversation that cannot be made; ``code`` says why."""
+
+ def __init__(self, code: str, detail: str = "") -> None:
+ super().__init__(detail or code)
+ self.code = code
+ self.detail = detail
+
+
+def _utcnow() -> datetime:
+ return datetime.now(timezone.utc)
+
+
+def _field(row: Any, name: str) -> Any:
+ return row.get(name) if isinstance(row, Mapping) else getattr(row, name, None)
+
+
+# ---- cursors -------------------------------------------------------------
+
+
+def conversation_digest(messages: Sequence[Any]) -> str:
+ """A digest of a stored conversation without the stamps the store adds
+ (``ts``), so the same messages read back give the same digest."""
+ plain = [{key: value for key, value in dict(message).items() if key != "ts"} for message in messages if isinstance(message, Mapping)]
+ data = json.dumps(plain, sort_keys=True, ensure_ascii=False, separators=(",", ":"), default=str)
+ return hashlib.sha256(data.encode("utf-8")).hexdigest()
+
+
+async def record_cursor(
+ database: Any, *, run_id: str, agent_node_id: str, generation: int, messages: Sequence[Any]
+) -> None:
+ """Keep where the agent's stored conversation stood as the run began.
+ Only the first time the agent is prepared in the run counts."""
+ async with database.reserved_session() as session:
+ run = await session.get(ChatRun, run_id)
+ if run is None or agent_node_id in (run.context_cursors or {}):
+ return
+ cursors = dict(run.context_cursors or {})
+ cursors[agent_node_id] = {
+ "generation": int(generation),
+ "length": len(messages),
+ "digest": conversation_digest(messages),
+ }
+ run.context_cursors = cursors
+ session.add(run)
+ await session.commit()
+
+
+# ---- the path ------------------------------------------------------------
+
+
+def active_path(rows: Sequence[Any], leaf_uid: Optional[str]) -> List[Any]:
+ """The rows from the first message to ``leaf_uid``, oldest first. A
+ session with no leaf recorded (or one gone) ends at its newest row."""
+ by_uid = {_field(row, "uid"): row for row in rows if _field(row, "uid")}
+ if not by_uid:
+ return []
+ leaf = by_uid.get(leaf_uid) if leaf_uid else None
+ if leaf is None:
+ leaf = max(by_uid.values(), key=lambda row: _field(row, "id") or 0)
+ path: List[Any] = []
+ seen: Set[str] = set()
+ current: Any = leaf
+ while current is not None and _field(current, "uid") not in seen:
+ seen.add(_field(current, "uid"))
+ path.append(current)
+ parent = _field(current, "parent_uid")
+ current = by_uid.get(parent) if parent else None
+ path.reverse()
+ return path
+
+
+def sibling_ids(rows: Sequence[Any]) -> Dict[str, List[str]]:
+ """Per message, the messages sharing its parent and role, oldest first
+ (itself included): its versions."""
+ groups: Dict[Tuple[Optional[str], Optional[str]], List[Any]] = {}
+ for row in sorted(rows, key=lambda row: _field(row, "id") or 0):
+ if _field(row, "uid"):
+ groups.setdefault((_field(row, "parent_uid"), _field(row, "role")), []).append(row)
+ siblings: Dict[str, List[str]] = {}
+ for group in groups.values():
+ ids = [_field(row, "uid") for row in group]
+ for uid in ids:
+ siblings[uid] = ids
+ return siblings
+
+
+def newest_leaf_under(rows: Sequence[Any], uid: str) -> str:
+ """The newest message in ``uid``'s branch: always a leaf, since a reply
+ is newer than what it follows. The branch a switch moves to ends there."""
+ children: Dict[Optional[str], List[Any]] = {}
+ for row in rows:
+ children.setdefault(_field(row, "parent_uid"), []).append(row)
+ by_uid = {_field(row, "uid"): row for row in rows}
+ best = by_uid[uid]
+ stack, seen = [uid], {uid}
+ while stack:
+ for child in children.get(stack.pop(), []):
+ child_uid = _field(child, "uid")
+ if child_uid in seen:
+ continue
+ seen.add(child_uid)
+ if (_field(child, "id") or 0) > (_field(best, "id") or 0):
+ best = child
+ stack.append(child_uid)
+ return _field(best, "uid")
+
+
+def _branch_rows(rows: Sequence[Any], top_uid: str, leaf_uid: str) -> List[Any]:
+ """The rows from ``top_uid`` down to ``leaf_uid``, oldest first."""
+ path = active_path(rows, leaf_uid)
+ uids = [_field(row, "uid") for row in path]
+ return path[uids.index(top_uid):] if top_uid in uids else []
+
+
+def answering_run_ids(path: Sequence[Any], runs: Sequence[Any]) -> Dict[str, str]:
+ """For each of the owner's messages on the path, the run answering it
+ there: the run of the answer after it on the path, else its newest run
+ (a retry still working), else the run it started."""
+ newest: Dict[str, Any] = {}
+ for run in runs:
+ message_uid = _field(run, "user_message_uid")
+ if not message_uid:
+ continue
+ known = newest.get(message_uid)
+ if known is None or (_field(run, "created_at"), _field(run, "run_id")) > (_field(known, "created_at"), _field(known, "run_id")):
+ newest[message_uid] = run
+ runs_by_id = {_field(run, "run_id"): run for run in runs}
+ answering: Dict[str, str] = {}
+ for index, row in enumerate(path):
+ if _field(row, "role") != "user":
+ continue
+ uid = _field(row, "uid")
+ after = path[index + 1] if index + 1 < len(path) else None
+ after_run = runs_by_id.get(_field(after, "run_id")) if after is not None and _field(after, "role") == "assistant" else None
+ if after_run is not None and _field(after_run, "user_message_uid") == uid:
+ answering[uid] = _field(after_run, "run_id")
+ elif uid in newest:
+ answering[uid] = _field(newest[uid], "run_id")
+ elif _field(row, "run_id"):
+ answering[uid] = _field(row, "run_id")
+ return answering
+
+
+def editable_ids(path: Sequence[Any], runs: Sequence[Any], live_root: Optional[str]) -> Set[str]:
+ """What the owner may change on the path, in the live generation: their
+ text messages a run answered (Edit), and the answer the path ends at,
+ once its run has ended (Try again)."""
+ if not live_root or not path:
+ return set()
+ runs_by_id = {_field(run, "run_id"): run for run in runs}
+ on_path = {_field(row, "uid") for row in path}
+ editable: Set[str] = set()
+ for row in path:
+ if (
+ _field(row, "role") == "user"
+ and (_field(row, "kind") or "text") in EDITABLE_KINDS
+ and _field(row, "run_id")
+ and _field(row, "execution_id") == live_root
+ ):
+ editable.add(_field(row, "uid"))
+ leaf = path[-1]
+ run = runs_by_id.get(_field(leaf, "run_id"))
+ if (
+ _field(leaf, "role") == "assistant"
+ and run is not None
+ and _field(run, "state") in TERMINAL_STATES
+ and _field(run, "run_key") == live_root
+ and _field(run, "user_message_uid") in on_path
+ ):
+ editable.add(_field(leaf, "uid"))
+ return editable
+
+
+# ---- moving --------------------------------------------------------------
+
+
+@dataclass
+class _Shape:
+ """What a move changes on the tree."""
+
+ #: The rows of the path it leaves, oldest first.
+ leaving: List[ChatMessage] = field(default_factory=list)
+ #: Runs taken back though none of their rows is left (a retried run
+ #: that never answered).
+ extra_run_ids: List[str] = field(default_factory=list)
+ #: The leaf of the branch left, the key its conversations are kept under
+ #: (None when nothing is left behind to come back to).
+ left_leaf: Optional[str] = None
+ #: The rows of the branch moved to, oldest first (a switch).
+ target: List[ChatMessage] = field(default_factory=list)
+ target_leaf: Optional[str] = None
+
+
+@dataclass
+class _Plan:
+ rewinds: Dict[str, Dict[str, Any]]
+ restores: Dict[str, ChatBranchSnapshot]
+ left_run_ids: List[str]
+
+ @property
+ def agents(self) -> Tuple[str, ...]:
+ return tuple(sorted(set(self.rewinds) | set(self.restores)))
+
+
+@dataclass
+class Moved:
+ """A move that committed: what ``after_move`` needs."""
+
+ session_id: str
+ workflow_id: str
+ generation: int
+ #: Conversations rewritten: ``(agent_node_id, message count)``.
+ changed: List[Tuple[str, int]]
+ #: Runs on the part of the path left behind.
+ left_run_ids: List[str]
+ #: What the operation wrote (a message and its run, or the new leaf).
+ result: Dict[str, Any] = field(default_factory=dict)
+
+
+def _ordered_runs(rows: Iterable[Any], extra: Iterable[str] = ()) -> List[str]:
+ seen: Set[str] = set()
+ ordered: List[str] = []
+ for run_id in [*extra, *(_field(row, "run_id") for row in rows)]:
+ if run_id and run_id not in seen:
+ seen.add(run_id)
+ ordered.append(run_id)
+ return ordered
+
+
+async def _runs(session: Any, run_ids: Sequence[str]) -> Dict[str, ChatRun]:
+ if not run_ids:
+ return {}
+ result = await session.execute(select(ChatRun).where(ChatRun.run_id.in_(list(run_ids))))
+ return {run.run_id: run for run in result.scalars().all()}
+
+
+async def _plan(session: Any, *, session_id: str, generation: int, shape: _Shape) -> _Plan:
+ left_run_ids = _ordered_runs(shape.leaving, shape.extra_run_ids)
+ runs = await _runs(session, left_run_ids)
+ rewinds: Dict[str, Dict[str, Any]] = {}
+ for run_id in left_run_ids:
+ run = runs.get(run_id)
+ for agent, cursor in ((run.context_cursors or {}) if run is not None else {}).items():
+ if agent not in rewinds and isinstance(cursor, dict):
+ rewinds[agent] = cursor
+ if any(int(cursor.get("generation", -1)) != generation for cursor in rewinds.values()):
+ raise BranchRefused("older_generation", "the conversation from before the employee restarted cannot change")
+ restores: Dict[str, ChatBranchSnapshot] = {}
+ if shape.target_leaf is not None:
+ target_runs = await _runs(session, _ordered_runs(shape.target))
+ touched = {agent for run in target_runs.values() for agent in (run.context_cursors or {})}
+ if touched:
+ found = await session.execute(
+ select(ChatBranchSnapshot).where(
+ ChatBranchSnapshot.session_id == session_id, ChatBranchSnapshot.leaf_uid == shape.target_leaf
+ )
+ )
+ saved = {snapshot.agent_node_id: snapshot for snapshot in found.scalars().all()}
+ for agent in touched:
+ snapshot = saved.get(agent)
+ if snapshot is None or snapshot.generation != generation:
+ raise BranchRefused("branch_unavailable", "that version of the conversation can no longer be restored")
+ restores[agent] = snapshot
+ return _Plan(rewinds=rewinds, restores=restores, left_run_ids=left_run_ids)
+
+
+def _size(messages: Sequence[Any]) -> int:
+ return len(json.dumps(list(messages), ensure_ascii=False, default=str).encode("utf-8"))
+
+
+async def _keep_snapshot(session: Any, *, session_id: str, leaf_uid: str, agent: str, generation: int, messages: List[Any]) -> None:
+ found = await session.execute(
+ select(ChatBranchSnapshot).where(
+ ChatBranchSnapshot.session_id == session_id,
+ ChatBranchSnapshot.leaf_uid == leaf_uid,
+ ChatBranchSnapshot.agent_node_id == agent,
+ )
+ )
+ snapshot = found.scalar_one_or_none()
+ if _size(messages) > branches_setting("max_snapshot_bytes"):
+ # Too large to keep: coming back to this branch is refused instead.
+ if snapshot is not None:
+ await session.delete(snapshot)
+ return
+ if snapshot is None:
+ snapshot = ChatBranchSnapshot(session_id=session_id, leaf_uid=leaf_uid, agent_node_id=agent)
+ snapshot.generation = generation
+ snapshot.messages = list(messages)
+ snapshot.created_at = _utcnow()
+ session.add(snapshot)
+
+
+async def _evict_snapshots(session: Any, session_id: str) -> None:
+ await session.flush()
+ keep = branches_setting("max_snapshots_per_session")
+ total = (
+ await session.execute(select(func.count()).select_from(ChatBranchSnapshot).where(ChatBranchSnapshot.session_id == session_id))
+ ).scalar() or 0
+ if total <= keep:
+ return
+ oldest = await session.execute(
+ select(ChatBranchSnapshot.id)
+ .where(ChatBranchSnapshot.session_id == session_id)
+ .order_by(ChatBranchSnapshot.created_at, ChatBranchSnapshot.id)
+ .limit(total - keep)
+ )
+ ids = [value for (value,) in oldest.all()]
+ if ids:
+ await session.execute(delete(ChatBranchSnapshot).where(ChatBranchSnapshot.id.in_(ids)))
+
+
+async def _apply(session: Any, plan: _Plan, *, session_id: str, workflow_id: str, generation: int, left_leaf: Optional[str]) -> List[Tuple[str, int]]:
+ agents = plan.agents
+ if not agents:
+ return []
+ found = await session.execute(
+ select(AgentConversation).where(
+ AgentConversation.workflow_id == workflow_id,
+ AgentConversation.generation == generation,
+ AgentConversation.agent_node_id.in_(list(agents)),
+ )
+ )
+ rows = {row.agent_node_id: row for row in found.scalars().all()}
+ stored = {agent: list(rows[agent].messages or []) if agent in rows else [] for agent in agents}
+ # Every agent taken back must still start the way it did then.
+ for agent, cursor in plan.rewinds.items():
+ if agent in plan.restores:
+ continue
+ length = int(cursor.get("length") or 0)
+ if len(stored[agent]) < length or conversation_digest(stored[agent][:length]) != cursor.get("digest"):
+ raise BranchRefused("cannot_rewind", "the employee has summarized or cleared what came before")
+ if left_leaf is not None:
+ for agent in plan.rewinds:
+ await _keep_snapshot(session, session_id=session_id, leaf_uid=left_leaf, agent=agent, generation=generation, messages=stored[agent])
+ changed: List[Tuple[str, int]] = []
+ now = _utcnow()
+ for agent in agents:
+ if agent in plan.restores:
+ new = list(plan.restores[agent].messages or [])
+ else:
+ new = stored[agent][: int(plan.rewinds[agent].get("length") or 0)]
+ if new == stored[agent]:
+ continue
+ row = rows.get(agent) or AgentConversation(workflow_id=workflow_id, generation=generation, agent_node_id=agent)
+ row.messages = new
+ row.updated_at = now
+ session.add(row)
+ changed.append((agent, len(new)))
+ await _evict_snapshots(session, session_id)
+ return changed
+
+
+async def _session_rows(session: Any, session_id: str) -> List[ChatMessage]:
+ result = await session.execute(select(ChatMessage).where(ChatMessage.session_id == session_id).order_by(ChatMessage.id))
+ return list(result.scalars().all())
+
+
+async def _lane_held(session: Any, session_id: str) -> bool:
+ result = await session.execute(
+ select(ChatRun.run_id)
+ .where(ChatRun.session_id == session_id, ChatRun.state.in_(LIVE_STATES), ChatRun.kind != "resume")
+ .limit(1)
+ )
+ return result.scalar_one_or_none() is not None
+
+
+class _Operation:
+ """One kind of move: where it forks (``shape``) and what it writes."""
+
+ async def shape(self, session: Any, rows: List[ChatMessage], path: List[ChatMessage]) -> _Shape:
+ raise NotImplementedError
+
+ async def write(self, session: Any, database: Any, thread: ChatThread, rows: List[ChatMessage], path: List[ChatMessage]) -> Dict[str, Any]:
+ raise NotImplementedError
+
+
+def _on_path(path: List[ChatMessage], uid: str) -> int:
+ for index, row in enumerate(path):
+ if row.uid == uid:
+ return index
+ raise BranchRefused("not_found", "that message is not in the conversation shown")
+
+
+def _new_run(*, session_id: str, workflow_id: str, live_root: str, kind: str, state: str, message_uid: str, parent_run_id: Optional[str]) -> ChatRun:
+ from services.chat.ledger import new_run_id, reply_uid
+
+ run_id = new_run_id()
+ return ChatRun(
+ run_id=run_id,
+ session_id=session_id,
+ workflow_id=workflow_id,
+ run_key=live_root,
+ kind=kind,
+ state=state,
+ user_message_uid=message_uid,
+ reply_message_uid=reply_uid(run_id),
+ parent_run_id=parent_run_id,
+ )
+
+
+@dataclass
+class _Edit(_Operation):
+ session_id: str
+ workflow_id: str
+ live_root: str
+ message_uid: str
+ text: str
+ state: str
+ uid: Optional[str] = None
+ meta: Dict[str, Any] = field(default_factory=dict)
+
+ async def shape(self, session: Any, rows: List[ChatMessage], path: List[ChatMessage]) -> _Shape:
+ index = _on_path(path, self.message_uid)
+ row = path[index]
+ if row.role != "user" or (row.kind or "text") not in EDITABLE_KINDS or not row.run_id:
+ raise BranchRefused("not_editable", "only your own messages the employee answered can be edited")
+ if row.execution_id != self.live_root:
+ raise BranchRefused("older_generation", "messages from before the employee restarted cannot be edited")
+ return _Shape(leaving=path[index:], left_leaf=path[-1].uid)
+
+ async def write(self, session: Any, database: Any, thread: ChatThread, rows: List[ChatMessage], path: List[ChatMessage]) -> Dict[str, Any]:
+ original = path[_on_path(path, self.message_uid)]
+ run = _new_run(
+ session_id=self.session_id, workflow_id=self.workflow_id, live_root=self.live_root, kind="edit",
+ state=self.state, message_uid="", parent_run_id=original.run_id,
+ )
+ row = await database.append_chat_row(
+ session,
+ session_id=self.session_id,
+ role="user",
+ message=self.text,
+ execution_id=self.live_root,
+ uid=self.uid,
+ run_id=run.run_id,
+ meta={**self.meta, "edit_of": original.uid},
+ after=original.parent_uid,
+ )
+ run.user_message_uid = row.uid
+ session.add(run)
+ return {"message": database.chat_row(row), "run": run, "prompt": self.text}
+
+
+@dataclass
+class _Retry(_Operation):
+ session_id: str
+ workflow_id: str
+ live_root: str
+ message_uid: str
+ state: str
+ question: Optional[ChatMessage] = None
+ retried: Optional[ChatRun] = None
+
+ async def shape(self, session: Any, rows: List[ChatMessage], path: List[ChatMessage]) -> _Shape:
+ index = _on_path(path, self.message_uid)
+ row = path[index]
+ if index != len(path) - 1:
+ raise BranchRefused("not_editable", "only the latest answer can be tried again")
+ if row.role == "assistant":
+ run = (await _runs(session, [row.run_id] if row.run_id else [])).get(row.run_id or "")
+ if run is None or not run.user_message_uid:
+ raise BranchRefused("not_editable", "this message did not come from a run")
+ question_index = _on_path(path, run.user_message_uid)
+ else:
+ answering = answering_run_ids(path, await _session_runs(session, self.session_id)).get(row.uid)
+ run = (await _runs(session, [answering] if answering else [])).get(answering or "")
+ if run is None:
+ raise BranchRefused("not_editable", "nothing answered this message")
+ question_index = index
+ if run.state not in TERMINAL_STATES:
+ raise BranchRefused("run_in_progress", "the employee is still answering")
+ question = path[question_index]
+ if run.run_key != self.live_root or question.execution_id != self.live_root:
+ raise BranchRefused("older_generation", "answers from before the employee restarted cannot be tried again")
+ self.question, self.retried = question, run
+ leaving = path[question_index + 1:]
+ return _Shape(leaving=leaving, extra_run_ids=[run.run_id], left_leaf=path[-1].uid if leaving else None)
+
+ async def write(self, session: Any, database: Any, thread: ChatThread, rows: List[ChatMessage], path: List[ChatMessage]) -> Dict[str, Any]:
+ assert self.question is not None and self.retried is not None
+ run = _new_run(
+ session_id=self.session_id, workflow_id=self.workflow_id, live_root=self.live_root, kind="regenerate",
+ state=self.state, message_uid=self.question.uid, parent_run_id=self.retried.run_id,
+ )
+ session.add(run)
+ thread.active_leaf_uid = self.question.uid
+ thread.revision = (thread.revision or 0) + 1
+ thread.updated_at = _utcnow()
+ session.add(thread)
+ return {"message": database.chat_row(self.question), "run": run, "prompt": _prompt_of(self.question)}
+
+
+@dataclass
+class _Switch(_Operation):
+ session_id: str
+ live_root: str
+ message_uid: str
+ leaf: Optional[str] = None
+
+ async def shape(self, session: Any, rows: List[ChatMessage], path: List[ChatMessage]) -> _Shape:
+ by_uid = {row.uid: row for row in rows}
+ target = by_uid.get(self.message_uid)
+ if target is None:
+ raise BranchRefused("not_found", "that version is not in this conversation")
+ if any(row.uid == target.uid for row in path):
+ # Already shown: nothing moves.
+ self.leaf = path[-1].uid if path else None
+ return _Shape()
+ beside = next((row for row in path if row.parent_uid == target.parent_uid and row.role == target.role), None)
+ if beside is None:
+ raise BranchRefused("not_found", "that version is not beside the conversation shown")
+ self.leaf = newest_leaf_under(rows, target.uid)
+ leaving = path[_on_path(path, beside.uid):]
+ arriving = _branch_rows(rows, target.uid, self.leaf)
+ if any(row.execution_id != self.live_root for row in [*leaving, *arriving]):
+ raise BranchRefused("older_generation", "the conversation from before the employee restarted cannot change")
+ return _Shape(leaving=leaving, left_leaf=path[-1].uid, target=arriving, target_leaf=self.leaf)
+
+ async def write(self, session: Any, database: Any, thread: ChatThread, rows: List[ChatMessage], path: List[ChatMessage]) -> Dict[str, Any]:
+ if self.leaf and thread.active_leaf_uid != self.leaf:
+ thread.active_leaf_uid = self.leaf
+ thread.revision = (thread.revision or 0) + 1
+ thread.updated_at = _utcnow()
+ session.add(thread)
+ return {"leaf": self.leaf}
+
+
+def _prompt_of(message: ChatMessage) -> str:
+ """What the employee reads for the owner's message: its text, or for a
+ button press the ``[ui-event]`` line it was sent as."""
+ event = (message.meta or {}).get("ui_event")
+ if message.kind == "action" and isinstance(event, dict):
+ from services.chat.parts import ui_event_message
+
+ return ui_event_message(
+ part_id=str(event.get("part_id") or ""),
+ element_id=str(event.get("element_id") or ""),
+ label=message.message,
+ action=str(event.get("action") or ""),
+ params=event.get("params") if isinstance(event.get("params"), dict) else {},
+ )
+ return message.message
+
+
+async def _session_runs(session: Any, session_id: str) -> List[ChatRun]:
+ result = await session.execute(select(ChatRun).where(ChatRun.session_id == session_id))
+ return list(result.scalars().all())
+
+
+async def _shape_and_plan(session: Any, *, session_id: str, generation: int, op: _Operation) -> Tuple[Optional[ChatThread], List[ChatMessage], List[ChatMessage], _Shape, _Plan]:
+ thread = await session.get(ChatThread, session_id)
+ rows = await _session_rows(session, session_id)
+ path = active_path(rows, thread.active_leaf_uid if thread is not None else None)
+ shape = await op.shape(session, rows, path)
+ plan = await _plan(session, session_id=session_id, generation=generation, shape=shape)
+ return thread, rows, path, shape, plan
+
+
+async def _move(
+ database: Any,
+ *,
+ session_id: str,
+ workflow_id: str,
+ generation: int,
+ expected_revision: Optional[int],
+ op: _Operation,
+) -> Moved:
+ from services.agent_context.conversation import conversation_lock
+
+ # A first look names the agents whose conversations may change, so
+ # their saves wait while the move runs.
+ async with database.get_session() as session:
+ _, _, _, _, first = await _shape_and_plan(session, session_id=session_id, generation=generation, op=op)
+ async with AsyncExitStack() as stack:
+ for agent in first.agents:
+ await stack.enter_async_context(conversation_lock(workflow_id, generation, agent))
+ async with database.reserved_session() as session:
+ thread = await session.get(ChatThread, session_id)
+ revision = thread.revision if thread is not None else 0
+ if expected_revision is not None and revision != expected_revision:
+ raise BranchRefused("revision_conflict", "the conversation changed meanwhile")
+ if await _lane_held(session, session_id):
+ raise BranchRefused("run_in_progress", "the employee is still answering")
+ thread, rows, path, shape, plan = await _shape_and_plan(session, session_id=session_id, generation=generation, op=op)
+ if plan.agents != first.agents:
+ raise BranchRefused("revision_conflict", "the conversation changed meanwhile")
+ if thread is None:
+ # A session written before threads existed: its path ends
+ # at its newest message.
+ thread = ChatThread(session_id=session_id, active_leaf_uid=path[-1].uid if path else None)
+ session.add(thread)
+ await session.flush()
+ changed = await _apply(session, plan, session_id=session_id, workflow_id=workflow_id, generation=generation, left_leaf=shape.left_leaf)
+ result = await op.write(session, database, thread, rows, path)
+ await session.commit()
+ return Moved(
+ session_id=session_id,
+ workflow_id=workflow_id,
+ generation=generation,
+ changed=changed,
+ left_run_ids=plan.left_run_ids,
+ result=result,
+ )
+
+
+async def edit_message(
+ database: Any,
+ *,
+ session_id: str,
+ workflow_id: str,
+ generation: int,
+ live_root: str,
+ message_uid: str,
+ text: str,
+ expected_revision: Optional[int],
+ state: str = "pending",
+ client_message_id: Optional[str] = None,
+) -> Moved:
+ """Add ``text`` as a new version of the owner's message ``message_uid``
+ and start the run that answers it (kind ``edit``). ``result`` holds
+ ``message``, ``run`` and ``prompt``."""
+ from services.chat.ledger import client_message_uid
+
+ uid = client_message_uid(session_id, client_message_id) if client_message_id is not None else None
+ meta = {"client_message_id": client_message_id} if client_message_id is not None else {}
+ op = _Edit(
+ session_id=session_id, workflow_id=workflow_id, live_root=live_root, message_uid=message_uid,
+ text=text, state=state, uid=uid, meta=meta,
+ )
+ return await _move(database, session_id=session_id, workflow_id=workflow_id, generation=generation, expected_revision=expected_revision, op=op)
+
+
+async def retry_answer(
+ database: Any,
+ *,
+ session_id: str,
+ workflow_id: str,
+ generation: int,
+ live_root: str,
+ message_uid: str,
+ expected_revision: Optional[int],
+ state: str = "pending",
+) -> Moved:
+ """Answer again the message the latest answer (``message_uid``) answered,
+ or the owner's latest message when its run gave no answer; the new answer
+ goes beside the old one (kind ``regenerate``). ``result`` holds
+ ``message`` (the owner's message answered), ``run`` and ``prompt``."""
+ op = _Retry(session_id=session_id, workflow_id=workflow_id, live_root=live_root, message_uid=message_uid, state=state)
+ return await _move(database, session_id=session_id, workflow_id=workflow_id, generation=generation, expected_revision=expected_revision, op=op)
+
+
+async def switch_branch(
+ database: Any,
+ *,
+ session_id: str,
+ workflow_id: str,
+ generation: int,
+ live_root: str,
+ message_uid: str,
+ expected_revision: Optional[int],
+) -> Moved:
+ """Show the version ``message_uid`` and the conversation after it.
+ ``result`` holds the new ``leaf``."""
+ op = _Switch(session_id=session_id, live_root=live_root, message_uid=message_uid)
+ return await _move(database, session_id=session_id, workflow_id=workflow_id, generation=generation, expected_revision=expected_revision, op=op)
+
+
+# ---- after a move ----------------------------------------------------------
+
+#: What a send on the part left still did, as the employee hears it.
+_STILL_DID = {"sent": "sent", "sending": "being sent"}
+
+
+async def after_move(database: Any, moved: Moved) -> None:
+ """What follows a committed move, each step best effort: the Context
+ panel hears of the conversations changed; drafts the runs on the part
+ left made that still wait are cancelled (nobody can see them any more);
+ and the employee is told what those runs sent anyway."""
+ from services.agent_context.listeners import notify_conversation_saved
+
+ for agent, count in moved.changed:
+ try:
+ await notify_conversation_saved(
+ workflow_id=moved.workflow_id, generation=moved.generation, agent_node_id=agent, message_count=count,
+ )
+ except Exception: # noqa: BLE001 - the panel refreshes on its next read
+ logger.warning("Context listeners were not told of a branch move", agent_node_id=agent, exc_info=True)
+ if not moved.left_run_ids:
+ return
+ try:
+ from services.approvals import store, waiter
+ from services.approvals.listeners import change_of, notify_approval_changed
+
+ for row in await store.cancel_open(database, workflow_id=moved.workflow_id, run_ids=moved.left_run_ids):
+ waiter.notify(row.id)
+ await notify_approval_changed(change_of(row, "cancelled"))
+ await _note_sends(database, moved)
+ except Exception: # noqa: BLE001 - the move stands; a draft left waiting still shows on its card
+ logger.warning("Drafts of a branch left were not settled", session_id=moved.session_id, exc_info=True)
+
+
+async def _note_sends(database: Any, moved: Moved) -> None:
+ from services.approvals import store
+ from services.chat.notes import upsert_note
+
+ rows = []
+ for run_id in moved.left_run_ids:
+ rows.extend(await store.list_approvals(database, workflow_id=moved.workflow_id, run_id=run_id, limit=100))
+ went = []
+ for row in rows:
+ result = _STILL_DID.get(row.status)
+ if result is None and row.status == "failed" and row.outcome == "unknown":
+ result = "may or may not have gone out"
+ if result is None:
+ continue
+ went.append({"what": row.action or f"{row.channel} message", "to": row.recipient_label or row.recipient or None, "result": result})
+ if not went:
+ return
+ payload = {
+ "note": (
+ "The owner went back to an earlier point in this chat, so what came after it is no longer part of the "
+ "conversation. These were sent on that part anyway."
+ ),
+ "sends": went,
+ }
+ text = f"[update]{json.dumps(payload, ensure_ascii=False, separators=(', ', ': '))}[/update]"
+ await upsert_note(database, session_id=moved.session_id, key=f"branch:{moved.left_run_ids[0]}", kind="update", text=text)
+
+
+__all__ = [
+ "BranchRefused",
+ "EDITABLE_KINDS",
+ "Moved",
+ "active_path",
+ "after_move",
+ "answering_run_ids",
+ "conversation_digest",
+ "edit_message",
+ "editable_ids",
+ "newest_leaf_under",
+ "record_cursor",
+ "retry_answer",
+ "sibling_ids",
+ "switch_branch",
+]
diff --git a/server/services/chat/config.py b/server/services/chat/config.py
index ebfcdc11..148ed2d2 100644
--- a/server/services/chat/config.py
+++ b/server/services/chat/config.py
@@ -33,4 +33,18 @@ def steps_setting(name: str) -> int:
return int(load_chat_config()["steps"][name])
-__all__ = ["CONFIG_PATH", "hub_setting", "load_chat_config", "runs_setting", "steps_setting", "stream_setting"]
+def branches_setting(name: str) -> int:
+ """``branches.<name>``: how many branch snapshots a session keeps, and
+ how large one may be."""
+ return int(load_chat_config()["branches"][name])
+
+
+__all__ = [
+ "CONFIG_PATH",
+ "branches_setting",
+ "hub_setting",
+ "load_chat_config",
+ "runs_setting",
+ "steps_setting",
+ "stream_setting",
+]
diff --git a/server/services/chat/feedback.py b/server/services/chat/feedback.py
new file mode 100644
index 00000000..ff980a39
--- /dev/null
+++ b/server/services/chat/feedback.py
@@ -0,0 +1,124 @@
+"""The owner's rating of an answer (docs-internal/chat_protocol.md,
+"Feedback").
+
+``set_feedback`` keeps it (``chat_feedback``, one per answer) and leaves the
+employee a note for its next turn in the chat (``[feedback]{...}[/feedback]``
+keyed per answer: changing the rating before that turn replaces the note,
+and taking it back drops one not yet told). It answers where the rating
+reaches: ``next_turn``, plus whatever a registered listener adds
+(``register_feedback_listener``; a plugin that keeps it somewhere the
+employee reads later answers that place, such as ``memory``).
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+from sqlmodel import select
+
+from core.logging import get_logger
+from models.chat import ChatFeedback
+from models.database import ChatMessage
+
+logger = get_logger(__name__)
+
+#: ``await listener(database=..., workflow_id=..., message=<row dict>,
+#: value="up"|"down")`` -> a reach it added (``"memory"``), or None.
+FeedbackListener = Callable[..., Awaitable[Optional[str]]]
+_LISTENERS: List[FeedbackListener] = []
+
+VALUES = ("up", "down")
+#: How much of the answer the note quotes.
+_EXCERPT_CHARS = 300
+
+
+class FeedbackRefused(ValueError):
+ """A rating that cannot be kept; ``code`` says why."""
+
+ def __init__(self, code: str) -> None:
+ super().__init__(code)
+ self.code = code
+
+
+def register_feedback_listener(listener: FeedbackListener) -> None:
+ """Run ``listener`` after each rating the owner gives (not a rating taken
+ back). Registering the same listener twice is a no-op."""
+ if listener not in _LISTENERS:
+ _LISTENERS.append(listener)
+
+
+def feedback_note(answer: str, value: str) -> str:
+ """The line the employee reads before its next answer."""
+ excerpt = " ".join((answer or "").split())
+ if len(excerpt) > _EXCERPT_CHARS:
+ excerpt = excerpt[: _EXCERPT_CHARS - 1].rstrip() + "…"
+ payload = {"rating": "good" if value == "up" else "bad", "answer": excerpt}
+ return f"[feedback]{json.dumps(payload, ensure_ascii=False, separators=(', ', ': '))}[/feedback]"
+
+
+async def set_feedback(database: Any, *, session_id: str, message_uid: str, value: Optional[str]) -> List[str]:
+ """Rate the answer ``message_uid`` (``up``, ``down``), or take the rating
+ back (None). Returns where it reaches. Raises :class:`FeedbackRefused`
+ (``invalid_request``, ``not_found``)."""
+ from services.chat.notes import drop_note, upsert_note
+
+ if value is not None and value not in VALUES:
+ raise FeedbackRefused("invalid_request")
+ async with database.reserved_session() as session:
+ found = await session.execute(
+ select(ChatMessage).where(ChatMessage.uid == message_uid, ChatMessage.session_id == session_id)
+ )
+ message = found.scalar_one_or_none()
+ if message is None or message.role != "assistant" or not message.run_id:
+ raise FeedbackRefused("not_found")
+ existing = (
+ await session.execute(
+ select(ChatFeedback).where(ChatFeedback.session_id == session_id, ChatFeedback.message_uid == message_uid)
+ )
+ ).scalar_one_or_none()
+ if value is None:
+ if existing is not None:
+ await session.delete(existing)
+ else:
+ row = existing or ChatFeedback(session_id=session_id, message_uid=message_uid, value=value)
+ row.value = value
+ row.updated_at = datetime.now(timezone.utc)
+ session.add(row)
+ row_dict = database.chat_row(message)
+ await session.commit()
+
+ key = f"feedback:{message_uid}"
+ if value is None:
+ await drop_note(database, session_id=session_id, key=key)
+ return []
+ await upsert_note(database, session_id=session_id, key=key, kind="feedback", text=feedback_note(row_dict["message"], value))
+ reaches = ["next_turn"]
+ for listener in list(_LISTENERS):
+ try:
+ reach = await listener(database=database, workflow_id=session_id, message=row_dict, value=value)
+ except Exception: # noqa: BLE001 - the note reaches the employee either way
+ logger.warning("Feedback listener failed", listener=getattr(listener, "__qualname__", repr(listener)), exc_info=True)
+ continue
+ if isinstance(reach, str) and reach and reach not in reaches:
+ reaches.append(reach)
+ return reaches
+
+
+async def feedback_for(database: Any, session_id: str) -> Dict[str, str]:
+ """The session's ratings, by answer."""
+ async with database.get_session() as session:
+ result = await session.execute(select(ChatFeedback).where(ChatFeedback.session_id == session_id))
+ return {row.message_uid: row.value for row in result.scalars().all()}
+
+
+__all__ = [
+ "FeedbackListener",
+ "FeedbackRefused",
+ "VALUES",
+ "feedback_for",
+ "feedback_note",
+ "register_feedback_listener",
+ "set_feedback",
+]
diff --git a/server/services/chat/guide.py b/server/services/chat/guide.py
index 0c39cf88..0814d3e4 100644
--- a/server/services/chat/guide.py
+++ b/server/services/chat/guide.py
@@ -32,7 +32,9 @@ CHAT_REPLY_GUIDE = (
"You are answering the owner in a chat.\n"
"- A line in square brackets at the start of the owner's message comes from OpenCompany, not from the owner: "
"[ui-event]{...}[/ui-event] is a button they pressed in an interface you showed (with what they picked), and "
- "[ui-state]{...}[/ui-state] is what they set in one without pressing anything. Treat it as the owner's choice.\n"
+ "[ui-state]{...}[/ui-state] is what they set in one without pressing anything; treat both as the owner's choice. "
+ "[update]{...}[/update] says what became of something you did (a draft sent or not, a part of the chat the owner "
+ "went back from), and [feedback]{...}[/feedback] is how the owner rated one of your answers; learn from it.\n"
"- A search result numbered n is a source: cite the ones you rely on as [n] right after what they support.\n"
"- When a few short next questions would help the owner, end your reply with "
'<followups>["...", "..."]</followups>: at most 3, each a short question in the owner\'s own words. The chat '
diff --git a/server/services/chat/handlers.py b/server/services/chat/handlers.py
index d388c6ed..f5d93ee3 100644
--- a/server/services/chat/handlers.py
+++ b/server/services/chat/handlers.py
@@ -12,19 +12,26 @@ the message starts a run, admitted in the same transaction
(``services/chat/ledger.py``), and the response names it. The editor's
``"default"`` session is saved and dispatched to every deployment, without a
run, as it always was.
+
+``get_chat_messages`` reads the path shown (``services/chat/branches.py``):
+each message with its versions (``siblings``), whether the owner may change
+it (``editable``) and their rating. ``edit_chat_message``,
+``regenerate_chat_reply`` and ``switch_chat_branch`` move that path, and
+``set_chat_feedback`` rates an answer (``services/chat/feedback.py``).
"""
from __future__ import annotations
from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
from fastapi import WebSocket
from core.container import container
from core.logging import get_logger
-from services.chat import ledger, reducer
+from services.chat import branches, ledger, reducer
from services.chat.access import ChatAccessDenied, authorize_session, session_id_of
+from services.chat.feedback import FeedbackRefused, feedback_for, set_feedback
from services.chat.events import MESSAGE_WIRE_ROUTING_KEY, dispatch_chat_message_received
from services.chat.hub import get_chat_hub
from services.chat_thread import (
@@ -62,9 +69,22 @@ def _wire_run(run: Any) -> Dict[str, Any]:
return wire
-def _wire_message(row: Dict[str, Any], runs: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
- """A stored message as ``get_chat_messages`` sends it."""
+def _wire_message(
+ row: Dict[str, Any],
+ runs: Optional[Dict[str, Any]] = None,
+ *,
+ siblings: Optional[List[str]] = None,
+ editable: bool = False,
+ feedback: Optional[str] = None,
+ run_id: Optional[str] = None,
+) -> Dict[str, Any]:
+ """A stored message as ``get_chat_messages`` sends it. ``siblings``: its
+ versions, oldest first (itself included); ``run_id``: the run answering
+ it on the path shown (an owner's message answered again names the newest
+ answer's run)."""
message_id = row.get("uid") or f"m{row.get('id')}"
+ versions = siblings if siblings and message_id in siblings else [message_id]
+ run_id = run_id or row.get("run_id")
wire: Dict[str, Any] = {
"id": message_id,
"legacy_id": row.get("id"),
@@ -74,20 +94,19 @@ def _wire_message(row: Dict[str, Any], runs: Optional[Dict[str, Any]] = None) ->
"message": row.get("message"),
"timestamp": row.get("timestamp"),
"run_key": row.get("execution_id"),
- "run_id": row.get("run_id"),
+ "run_id": run_id,
"parent_id": row.get("parent_uid"),
"status": row.get("status") or "complete",
"attachments": row.get("attachments") or [],
"parts": row.get("parts") or {},
- "feedback": None,
- "siblings": {"index": 0, "count": 1, "ids": [message_id]},
- # Editing arrives with branches; until then no message is editable.
- "editable": False,
+ "feedback": feedback,
+ "siblings": {"index": versions.index(message_id), "count": len(versions), "ids": list(versions)},
+ "editable": editable,
}
client_message_id = (row.get("meta") or {}).get("client_message_id")
if client_message_id:
wire["client_message_id"] = client_message_id
- run = (runs or {}).get(row.get("run_id") or "")
+ run = (runs or {}).get(run_id or "")
if run is not None:
wire["run"] = _wire_run(run)
return wire
@@ -162,6 +181,18 @@ async def _ui_event(database: Any, session_id: str, raw: Any) -> Dict[str, Any]:
}
+async def _dispatch(
+ session_id: str, workflow_id: Optional[str], *, message_uid: str, prompt: str, run_id: Optional[str], timestamp: str
+) -> None:
+ """Send the owner's message to the workflow's chat triggers: the run it
+ starts is the event's id, so the trigger's child workflow is the run's."""
+ event_data: Dict[str, Any] = {"message": prompt, "timestamp": timestamp, "session_id": session_id, "message_id": message_uid}
+ if run_id is not None:
+ event_data["run_id"] = run_id
+ await dispatch_chat_message_received(event_data, workflow_id=workflow_id, event_id=run_id)
+ logger.info("Chat message dispatched", session_id=session_id, run_id=run_id)
+
+
@ws_handler("message")
async def handle_send_chat_message(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
"""Save the owner's message, start its run, and dispatch it. Answers
@@ -232,20 +263,14 @@ async def handle_send_chat_message(data: Dict[str, Any], websocket: WebSocket) -
row, run = admission.message, admission.run
if admission.created:
await announce_chat_updated(session_id, "user")
- event_data: Dict[str, Any] = {
- "message": press["prompt"] if press is not None else message,
- "timestamp": timestamp,
- "session_id": session_id,
- "message_id": row["uid"],
- }
- if run is not None:
- event_data["run_id"] = run.run_id
- await dispatch_chat_message_received(
- event_data,
- workflow_id=scope.workflow_id,
- event_id=run.run_id if run is not None else None,
+ await _dispatch(
+ session_id,
+ scope.workflow_id,
+ message_uid=row["uid"],
+ prompt=press["prompt"] if press is not None else message,
+ run_id=run.run_id if run is not None else None,
+ timestamp=timestamp,
)
- logger.info("Chat message dispatched", session_id=session_id, run_id=run.run_id if run is not None else None)
response: Dict[str, Any] = {
"success": True,
@@ -261,41 +286,55 @@ async def handle_send_chat_message(data: Dict[str, Any], websocket: WebSocket) -
@ws_handler()
async def handle_get_chat_messages(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
- """A session's messages, oldest first, the newest ``limit`` of them, with
- the thread's state and its live runs. The live generation's messages
- only, unless ``all_generations`` (Home's thread, which also shows a
- message from before a Start). A read that fails answers ``read_failed``,
- never an empty thread."""
+ """The path shown in a session (``services/chat/branches.py``), oldest
+ first, the newest ``limit`` of it, with the thread's state and its live
+ runs. The live generation's messages only, unless ``all_generations``
+ (Home's thread, which also shows a message from before a Start). Each
+ message carries its versions, whether the owner may change it now
+ (``editable``: edit theirs, try the latest answer again) and their
+ rating. A read that fails answers ``read_failed``, never an empty
+ thread."""
session_id = session_id_of(data)
limit = data.get("limit")
database = container.database()
try:
- await authorize_session(database, websocket, session_id)
+ scope = await authorize_session(database, websocket, session_id)
except ChatAccessDenied:
return dict(_DENIED)
try:
- if data.get("all_generations"):
- rows = await database.read_chat_messages(session_id, limit)
- else:
- control = await database.get_latest_workflow_control(session_id)
- if control is not None and control.status == "reset":
- rows = []
- else:
- rows = await database.read_chat_messages(
- session_id, limit,
- execution_id=control.root_execution_id if control is not None else None,
- )
+ rows = await database.read_chat_messages(session_id)
thread = await _thread_state(database, session_id)
+ control = await database.get_latest_workflow_control(session_id) if scope.workflow_id is not None else None
+ path = branches.active_path(rows, thread["active_leaf_id"])
+ if not data.get("all_generations") and control is not None:
+ path = [] if control.status == "reset" else [row for row in path if row.get("execution_id") == control.root_execution_id]
+ runs_list = await ledger.session_runs(database, session_id)
+ runs = {run.run_id: run for run in runs_list}
+ answering = branches.answering_run_ids(path, runs_list)
+ editable = branches.editable_ids(path, runs_list, chat_execution_id(control)) if scope.workflow_id is not None else set()
+ siblings = branches.sibling_ids(rows)
+ ratings = await feedback_for(database, session_id)
active_runs = await run_snapshots(database, session_id)
- runs = await ledger.runs_by_id(database, [row.get("run_id") for row in rows])
except Exception:
logger.warning("Chat messages could not be read", session_id=session_id, exc_info=True)
return {"success": False, "error": "read_failed", "session_id": session_id}
+ if isinstance(limit, int) and not isinstance(limit, bool) and limit > 0:
+ path = path[-limit:]
return {
"success": True,
"protocol_version": PROTOCOL_VERSION,
"session_id": session_id,
- "messages": [_wire_message(row, runs) for row in rows],
+ "messages": [
+ _wire_message(
+ row,
+ runs,
+ siblings=siblings.get(row.get("uid") or ""),
+ editable=row.get("uid") in editable,
+ feedback=ratings.get(row.get("uid") or ""),
+ run_id=answering.get(row.get("uid") or ""),
+ )
+ for row in path
+ ],
"thread": thread,
"active_runs": active_runs,
}
@@ -406,6 +445,205 @@ async def handle_chat_ui_state(data: Dict[str, Any], websocket: WebSocket) -> Di
return {"success": True, "part_id": part_id, "state_revision": updated["state_revision"]}
+def _expected_revision(data: Dict[str, Any]) -> Optional[int]:
+ value = data.get("expected_revision")
+ if value is None:
+ return None
+ if isinstance(value, bool) or not isinstance(value, int):
+ raise ValueError("expected_revision is the thread's revision, a number")
+ return value
+
+
+async def _branch_context(
+ database: Any, websocket: WebSocket, data: Dict[str, Any], *, starts_run: bool
+) -> Tuple[Optional[Dict[str, Any]], Dict[str, Any]]:
+ """The workflow session a branch command changes, with its live
+ generation and (for a command that starts a run) where a message goes
+ now; or the refusal."""
+ session_id = session_id_of(data)
+ try:
+ scope = await authorize_session(database, websocket, session_id)
+ except ChatAccessDenied:
+ return dict(_DENIED), {}
+ if scope.workflow_id is None:
+ return {"success": False, "error": "not_editable", "detail": "this chat keeps no versions"}, {}
+ try:
+ revision = _expected_revision(data)
+ except ValueError as exc:
+ return {"success": False, "error": "invalid_request", "detail": str(exc)}, {}
+ control = await database.get_latest_workflow_control(session_id)
+ live_root = chat_execution_id(control)
+ if control is None or live_root is None:
+ return {"success": False, "error": "not_running"}, {}
+ context: Dict[str, Any] = {
+ "session_id": session_id,
+ "workflow_id": scope.workflow_id,
+ "generation": int(control.generation),
+ "live_root": live_root,
+ "expected_revision": revision,
+ "delivery": None,
+ "state": "pending",
+ }
+ if starts_run:
+ delivery = delivery_for(control)
+ if delivery is None or not await _answers_session(database, control, session_id):
+ return {"success": False, "error": "not_running"}, {}
+ context["delivery"] = delivery
+ context["state"] = "queued" if delivery == "queued" else "pending"
+ return None, context
+
+
+def _branch_refusal(exc: "branches.BranchRefused") -> Dict[str, Any]:
+ return {"success": False, "error": exc.code, "detail": exc.detail}
+
+
+async def _answer_branch(database: Any, moved: "branches.Moved", context: Dict[str, Any], *, role: Optional[str], timestamp: str) -> Dict[str, Any]:
+ """After an edit or a retry committed: settle what the part left made,
+ tell open threads, and send the message to the chat triggers."""
+ await branches.after_move(database, moved)
+ await announce_chat_updated(moved.session_id, role)
+ message, run = moved.result["message"], moved.result["run"]
+ await _dispatch(
+ moved.session_id, moved.workflow_id, message_uid=message["uid"], prompt=moved.result["prompt"], run_id=run.run_id, timestamp=timestamp,
+ )
+ response: Dict[str, Any] = {"success": True, "message_id": message["uid"], "run_id": run.run_id}
+ if context.get("delivery") is not None:
+ response["delivery"] = context["delivery"]
+ return response
+
+
+@ws_handler("message_id", "message")
+async def handle_edit_chat_message(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """Edit one of the owner's messages (``message_id``): the edit goes
+ beside it as its new version, and the employee answers it remembering the
+ conversation as it stood before the original. Answers ``{message_id,
+ run_id, delivery}``; a resent edit (the same ``client_message_id``)
+ answers the first. Refused with ``not_editable``, ``older_generation``,
+ ``revision_conflict`` (``expected_revision`` is not the thread's),
+ ``run_in_progress``, ``cannot_rewind``, ``not_found``, ``not_running``,
+ ``access_denied``, ``invalid_request`` or ``save_failed``."""
+ text = data.get("message")
+ if not isinstance(text, str) or not text.strip():
+ return {"success": False, "error": "invalid_request", "detail": "message must be text"}
+ database = container.database()
+ refused, context = await _branch_context(database, websocket, data, starts_run=True)
+ if refused is not None:
+ return refused
+ client_message_id = data.get("client_message_id")
+ if client_message_id is not None:
+ try:
+ uid = ledger.client_message_uid(context["session_id"], client_message_id)
+ except ValueError as exc:
+ return {"success": False, "error": "invalid_request", "detail": str(exc)}
+ sent = await ledger.saved_message(database, uid)
+ if sent is not None:
+ return {"success": True, "message_id": sent.uid, "run_id": sent.run_id, "delivery": context["delivery"]}
+ try:
+ moved = await branches.edit_message(
+ database,
+ session_id=context["session_id"],
+ workflow_id=context["workflow_id"],
+ generation=context["generation"],
+ live_root=context["live_root"],
+ message_uid=str(data["message_id"]),
+ text=text.strip(),
+ expected_revision=context["expected_revision"],
+ state=context["state"],
+ client_message_id=client_message_id,
+ )
+ except branches.BranchRefused as exc:
+ return _branch_refusal(exc)
+ except Exception:
+ logger.warning("Chat message could not be edited", session_id=context["session_id"], exc_info=True)
+ return {"success": False, "error": "save_failed"}
+ timestamp = data.get("timestamp") or datetime.now(timezone.utc).isoformat()
+ return await _answer_branch(database, moved, context, role="user", timestamp=timestamp)
+
+
+@ws_handler("message_id")
+async def handle_regenerate_chat_reply(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """Try again: answer anew the message the latest answer (``message_id``)
+ answered, or the owner's last message when its run gave no answer. The
+ new answer goes beside the old one, and the employee writes it
+ remembering the conversation as it stood before the old one. Answers
+ ``{message_id (the owner's message), run_id, delivery}``. Refused like
+ ``edit_chat_message``."""
+ database = container.database()
+ refused, context = await _branch_context(database, websocket, data, starts_run=True)
+ if refused is not None:
+ return refused
+ try:
+ moved = await branches.retry_answer(
+ database,
+ session_id=context["session_id"],
+ workflow_id=context["workflow_id"],
+ generation=context["generation"],
+ live_root=context["live_root"],
+ message_uid=str(data["message_id"]),
+ expected_revision=context["expected_revision"],
+ state=context["state"],
+ )
+ except branches.BranchRefused as exc:
+ return _branch_refusal(exc)
+ except Exception:
+ logger.warning("Chat answer could not be tried again", session_id=context["session_id"], exc_info=True)
+ return {"success": False, "error": "save_failed"}
+ timestamp = data.get("timestamp") or datetime.now(timezone.utc).isoformat()
+ return await _answer_branch(database, moved, context, role=None, timestamp=timestamp)
+
+
+@ws_handler("message_id")
+async def handle_switch_chat_branch(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """Show another version (``message_id``: a message beside one on the
+ path) and the conversation after it, the employee remembering that
+ branch. Answers ``{leaf_id}``. Refused with ``branch_unavailable`` (its
+ conversations are no longer kept), ``cannot_rewind``,
+ ``older_generation``, ``revision_conflict``, ``run_in_progress``,
+ ``not_found``, ``not_running``, ``access_denied`` or ``save_failed``."""
+ database = container.database()
+ refused, context = await _branch_context(database, websocket, data, starts_run=False)
+ if refused is not None:
+ return refused
+ try:
+ moved = await branches.switch_branch(
+ database,
+ session_id=context["session_id"],
+ workflow_id=context["workflow_id"],
+ generation=context["generation"],
+ live_root=context["live_root"],
+ message_uid=str(data["message_id"]),
+ expected_revision=context["expected_revision"],
+ )
+ except branches.BranchRefused as exc:
+ return _branch_refusal(exc)
+ except Exception:
+ logger.warning("Chat branch could not be switched", session_id=context["session_id"], exc_info=True)
+ return {"success": False, "error": "save_failed"}
+ await branches.after_move(database, moved)
+ await announce_chat_updated(moved.session_id, None)
+ return {"success": True, "leaf_id": moved.result.get("leaf")}
+
+
+@ws_handler("message_id")
+async def handle_set_chat_feedback(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
+ """Rate an answer (``value``: ``up`` or ``down``) or take the rating back
+ (``null``). Answers where it reaches (``reaches``: ``next_turn``, and
+ ``memory`` when the employee keeps it too); ``not_found`` for a message
+ that is not an answer in this chat."""
+ session_id = session_id_of(data)
+ database = container.database()
+ try:
+ await authorize_session(database, websocket, session_id)
+ except ChatAccessDenied:
+ return dict(_DENIED)
+ value = data.get("value")
+ try:
+ reaches = await set_feedback(database, session_id=session_id, message_uid=str(data["message_id"]), value=value)
+ except FeedbackRefused as exc:
+ return {"success": False, "error": exc.code}
+ return {"success": True, "message_id": str(data["message_id"]), "value": value, "reaches": reaches}
+
+
@ws_handler()
async def handle_clear_chat_messages(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
"""Clear a session's chat, every generation of it, with its runs. For a
@@ -445,6 +683,10 @@ WS_HANDLERS = {
"get_chat_run": handle_get_chat_run,
"stop_chat_run": handle_stop_chat_run,
"chat_ui_state": handle_chat_ui_state,
+ "edit_chat_message": handle_edit_chat_message,
+ "regenerate_chat_reply": handle_regenerate_chat_reply,
+ "switch_chat_branch": handle_switch_chat_branch,
+ "set_chat_feedback": handle_set_chat_feedback,
"clear_chat_messages": handle_clear_chat_messages,
"save_chat_message": handle_save_chat_message,
}
diff --git a/server/services/chat/ledger.py b/server/services/chat/ledger.py
index c86c2686..630270b7 100644
--- a/server/services/chat/ledger.py
+++ b/server/services/chat/ledger.py
@@ -174,6 +174,22 @@ async def ui_part_of_run(database: Any, run_id: str) -> Optional[str]:
return part_id if isinstance(part_id, str) and part_id else None
+async def saved_message(database: Any, uid: str) -> Optional[ChatMessage]:
+ """The message saved under ``uid``, if any."""
+ async with database.get_session() as session:
+ result = await session.execute(select(ChatMessage).where(ChatMessage.uid == uid))
+ return result.scalar_one_or_none()
+
+
+async def session_runs(database: Any, session_id: str) -> List[ChatRun]:
+ """Every run of a session, live or ended, oldest first."""
+ async with database.get_session() as session:
+ result = await session.execute(
+ select(ChatRun).where(ChatRun.session_id == session_id).order_by(ChatRun.created_at, ChatRun.run_id)
+ )
+ return list(result.scalars().all())
+
+
async def session_run_ids(database: Any, session_id: str) -> List[str]:
"""Every run of a session, live or ended."""
async with database.get_session() as session:
@@ -734,7 +750,9 @@ __all__ = [
"reply_uid",
"request_stop",
"runs_by_id",
+ "saved_message",
"session_run_ids",
+ "session_runs",
"start_run",
"ui_part_of_run",
"sweep",
diff --git a/server/services/chat/notes.py b/server/services/chat/notes.py
index 929b56b4..ed710656 100644
--- a/server/services/chat/notes.py
+++ b/server/services/chat/notes.py
@@ -95,6 +95,18 @@ async def deliver_notes(database: Any, run_id: str) -> int:
return told
+async def drop_note(database: Any, *, session_id: str, key: str) -> None:
+ """Forget the note under ``key`` if it was not told yet (what it said no
+ longer holds, such as a rating taken back)."""
+ from sqlalchemy import delete
+
+ async with database.get_session() as session:
+ await session.execute(
+ delete(ChatNote).where(ChatNote.session_id == session_id, ChatNote.key == key, ChatNote.delivered_at.is_(None))
+ )
+ await session.commit()
+
+
async def clear_notes(database: Any, session_id: str) -> None:
"""Forget a session's notes (its conversation was cleared or reset)."""
from sqlalchemy import delete
@@ -109,4 +121,4 @@ def notes_prompt(notes: List[ChatNote]) -> str:
return "\n".join(note.text for note in notes)
-__all__ = ["MAX_NOTES_PER_TURN", "claim_notes", "clear_notes", "deliver_notes", "notes_prompt", "upsert_note"]
+__all__ = ["MAX_NOTES_PER_TURN", "claim_notes", "clear_notes", "deliver_notes", "drop_note", "notes_prompt", "upsert_note"]
diff --git a/server/services/temporal/agent_activities.py b/server/services/temporal/agent_activities.py
index 1f4f2dca..e35b6e8c 100644
--- a/server/services/temporal/agent_activities.py
+++ b/server/services/temporal/agent_activities.py
@@ -912,6 +912,27 @@ async def store_agent_output(payload: Dict[str, Any]) -> Dict[str, Any]:
return {"stored": True}
+async def _record_chat_cursor(
+ database: Any, context: Dict[str, Any], *, node_id: str, generation: int, stored: List[Dict[str, Any]]
+) -> None:
+ """Keep, on the chat run this agent works for, where its stored
+ conversation stood as the run began, so editing the owner's message or
+ trying an answer again can take it back there
+ (``services/chat/branches.py``). Best effort: a run that kept none
+ leaves this agent's memory as it is when the chat moves."""
+ from services.chat.stream import chat_run_id_of
+
+ run_id = chat_run_id_of(context)
+ if not run_id:
+ return
+ try:
+ from services.chat.branches import record_cursor
+
+ await record_cursor(database, run_id=run_id, agent_node_id=node_id, generation=generation, messages=stored)
+ except Exception: # noqa: BLE001 - the run goes on; only rewinding past it is lost
+ activity.logger.warning("Chat run cursor not recorded for agent %s", node_id, exc_info=True)
+
+
@activity.defn(name="agent.prepare_payload")
async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
"""Resolve everything ``AgentWorkflow`` needs from the canvas + DB.
@@ -1270,14 +1291,10 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
from services.agent_context import load_conversation
from services.agent_context.conversation import close_unanswered_tool_calls
+ stored = await load_conversation(database, **conversation_key)
# A run stopped or crashed mid-tool left calls without results,
# which no provider accepts: answer them before continuing.
- conversation = close_unanswered_tool_calls(
- await load_conversation(
- database,
- **conversation_key,
- )
- )
+ conversation = close_unanswered_tool_calls(stored)
except Exception as exc:
raise ApplicationError(
f"Conversation load failed for agent {node_id!r} "
@@ -1300,6 +1317,7 @@ async def prepare_agent_payload(context: Dict[str, Any]) -> Dict[str, Any]:
type="ConversationTooLarge",
non_retryable=True,
)
+ await _record_chat_cursor(database, context, node_id=node_id, generation=generation, stored=stored)
# ---- Tools ----------------------------------------------------------
# We call ``ai_service._build_tool_from_node`` once here ONLY to
diff --git a/server/tests/services/chat/test_branches.py b/server/tests/services/chat/test_branches.py
new file mode 100644
index 00000000..43d3d4f3
--- /dev/null
+++ b/server/tests/services/chat/test_branches.py
@@ -0,0 +1,354 @@
+"""Branches of a chat (services/chat/branches.py): the path shown and the
+messages beside each one; an edit goes beside the message it edits and the
+agent's memory goes back to before it; trying the latest answer again;
+switching between versions restores what the agent remembered on each;
+every move refused when the conversation changed, a run is answering, the
+memory no longer starts the way it did, or the messages are from before a
+restart; drafts of the part left are cancelled and the employee hears of
+what it sent there anyway; ratings."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+import pytest
+
+from services.agent_context.conversation import load_conversation, save_conversation
+from services.chat import branches, ledger, notes
+from tests.services.chat._helpers import add_control, talking
+
+AGENT = "wf:aiAgent:1"
+CLAIM = dict(temporal_workflow_id="tw-1", temporal_run_id="tr-1")
+
+
+def turn(text: str) -> List[Dict[str, Any]]:
+ return [{"role": "user", "content": text}, {"role": "assistant", "content": f"re: {text}"}]
+
+
+async def memory(database) -> List[Dict[str, Any]]:
+ stored = await load_conversation(database, workflow_id="wf", generation=1, agent_node_id=AGENT)
+ return [{key: value for key, value in message.items() if key != "ts"} for message in stored]
+
+
+async def answer(database, run_id: str, text: str, *, before: List[Dict[str, Any]], after: List[Dict[str, Any]]) -> Dict[str, Any]:
+ """The run answers as a deployed agent would: it loads ``before`` (the
+ cursor), saves ``after``, posts ``text`` and finishes."""
+ run = await ledger.start_run(database, run_id=run_id, **CLAIM)
+ assert run is not None
+ await branches.record_cursor(database, run_id=run_id, agent_node_id=AGENT, generation=1, messages=before)
+ await save_conversation(database, workflow_id="wf", generation=1, agent_node_id=AGENT, messages=after)
+ reply = await ledger.post_reply(database, run=run, node_id="wf:chatReply:1", text=text, execution_id="gen-1")
+ await ledger.finish_run(database, run_id=run_id, success=True, **CLAIM)
+ return reply
+
+
+async def thread(chat, **extra) -> Dict[str, Any]:
+ reply = await chat.handlers.handle_get_chat_messages({"session_id": "wf", **extra}, None)
+ assert reply["success"] is True
+ return reply
+
+
+async def path(chat) -> List[str]:
+ return [message["text"] for message in (await thread(chat))["messages"]]
+
+
+async def revision(chat) -> int:
+ return (await thread(chat))["thread"]["revision"]
+
+
+async def conversation(chat):
+ """Book Saturday -> answered (memory: the turn)."""
+ await talking(chat.database)
+ sent = await chat.handlers.handle_send_chat_message({"message": "Book Saturday", "session_id": "wf"}, None)
+ await answer(chat.database, sent["run_id"], "Saturday is booked.", before=[], after=turn("Book Saturday"))
+ return sent
+
+
+# ----- the path ---------------------------------------------------------------
+
+
+def row(id: int, uid: str, parent: Any, role: str = "user", **extra: Any) -> Dict[str, Any]:
+ return {"id": id, "uid": uid, "parent_uid": parent, "role": role, "kind": "text", "execution_id": "gen-1", **extra}
+
+
+def test_the_path_follows_the_leaf_and_versions_share_a_parent():
+ rows = [
+ row(1, "m1", None),
+ row(2, "a1", "m1", "assistant"),
+ row(3, "m2", "a1"),
+ row(4, "m2b", "a1"),
+ row(5, "a2b", "m2b", "assistant"),
+ ]
+ assert [r["uid"] for r in branches.active_path(rows, "m2")] == ["m1", "a1", "m2"]
+ # No leaf (or one gone): the newest message.
+ assert [r["uid"] for r in branches.active_path(rows, "gone")] == ["m1", "a1", "m2b", "a2b"]
+ siblings = branches.sibling_ids(rows)
+ assert siblings["m2"] == siblings["m2b"] == ["m2", "m2b"]
+ assert siblings["a2b"] == ["a2b"] and siblings["m1"] == ["m1"]
+ assert branches.newest_leaf_under(rows, "m2b") == "a2b"
+ assert branches.newest_leaf_under(rows, "m2") == "m2"
+
+
+def test_who_answers_each_message_and_what_may_change():
+ rows = [row(1, "m1", None, run_id="r1"), row(2, "a2", "m1", "assistant", run_id="r2")]
+ runs = [
+ {"run_id": "r1", "user_message_uid": "m1", "created_at": 1, "state": "finished", "run_key": "gen-1"},
+ {"run_id": "r2", "user_message_uid": "m1", "created_at": 2, "state": "finished", "run_key": "gen-1"},
+ ]
+ # The answer on the path names the run answering the owner's message.
+ assert branches.answering_run_ids(rows, runs) == {"m1": "r2"}
+ assert branches.editable_ids(rows, runs, "gen-1") == {"m1", "a2"}
+ # Not in the live generation, nothing.
+ assert branches.editable_ids(rows, runs, "gen-2") == set()
+ live = [dict(runs[0]), {**runs[1], "state": "running"}]
+ assert branches.editable_ids(rows, live, "gen-1") == {"m1"}
+
+
+async def test_a_cursor_keeps_the_first_reading(database):
+ await talking(database)
+ admission = await ledger.admit_message(database, session_id="wf", workflow_id="wf", execution_id="gen-1", text="Hi", track=True)
+ run_id = admission.run.run_id
+ await branches.record_cursor(database, run_id=run_id, agent_node_id=AGENT, generation=1, messages=turn("a"))
+ await branches.record_cursor(database, run_id=run_id, agent_node_id=AGENT, generation=1, messages=[])
+ cursor = (await ledger.get_run(database, run_id)).context_cursors[AGENT]
+ assert cursor == {"generation": 1, "length": 2, "digest": branches.conversation_digest(turn("a"))}
+ # Stamps the store adds do not change it.
+ stamped = [{**message, "ts": "2026-10-04T09:00:00+00:00"} for message in turn("a")]
+ assert branches.conversation_digest(stamped) == cursor["digest"]
+
+
+# ----- editing ------------------------------------------------------------------
+
+
+async def test_an_edit_goes_beside_the_message_and_the_agent_forgets_what_followed(chat):
+ first = await conversation(chat)
+ edited = await chat.handlers.handle_edit_chat_message(
+ {"session_id": "wf", "message_id": first["message_id"], "message": "Book Sunday", "expected_revision": await revision(chat)}, None
+ )
+ assert edited["success"] is True and edited["delivery"] == "now"
+ # The agent remembers the conversation as it was before the original.
+ assert await memory(chat.database) == []
+ shown = (await thread(chat))["messages"]
+ assert [message["text"] for message in shown] == ["Book Sunday"]
+ assert shown[0]["siblings"] == {"index": 1, "count": 2, "ids": [first["message_id"], edited["message_id"]]}
+ assert shown[0]["run_id"] == edited["run_id"]
+ run = await ledger.get_run(chat.database, edited["run_id"])
+ assert (run.kind, run.user_message_uid, run.parent_run_id) == ("edit", edited["message_id"], first["run_id"])
+ # The employee is asked to answer the edit.
+ assert chat.dispatched[-1]["data"]["message"] == "Book Sunday" and chat.dispatched[-1]["event_id"] == edited["run_id"]
+
+
+async def test_switching_back_restores_what_the_agent_remembered_there(chat):
+ first = await conversation(chat)
+ edited = await chat.handlers.handle_edit_chat_message(
+ {"session_id": "wf", "message_id": first["message_id"], "message": "Book Sunday", "expected_revision": await revision(chat)}, None
+ )
+ await answer(chat.database, edited["run_id"], "Sunday is booked.", before=[], after=turn("Book Sunday"))
+
+ back = await chat.handlers.handle_switch_chat_branch(
+ {"session_id": "wf", "message_id": first["message_id"], "expected_revision": await revision(chat)}, None
+ )
+ assert back["success"] is True
+ assert await path(chat) == ["Book Saturday", "Saturday is booked."]
+ assert await memory(chat.database) == turn("Book Saturday")
+ forward = await chat.handlers.handle_switch_chat_branch(
+ {"session_id": "wf", "message_id": edited["message_id"], "expected_revision": await revision(chat)}, None
+ )
+ assert forward["success"] is True
+ assert await path(chat) == ["Book Sunday", "Sunday is booked."]
+ assert await memory(chat.database) == turn("Book Sunday")
+ # Already shown: nothing moves.
+ again = await chat.handlers.handle_switch_chat_branch({"session_id": "wf", "message_id": edited["message_id"]}, None)
+ assert again["success"] is True and await path(chat) == ["Book Sunday", "Sunday is booked."]
+
+
+async def test_trying_again_answers_the_same_message_beside_the_old_answer(chat):
+ first = await conversation(chat)
+ shown = (await thread(chat))["messages"]
+ assert [message["editable"] for message in shown] == [True, True]
+ retried = await chat.handlers.handle_regenerate_chat_reply(
+ {"session_id": "wf", "message_id": shown[1]["id"], "expected_revision": await revision(chat)}, None
+ )
+ assert retried["success"] is True and retried["message_id"] == first["message_id"]
+ assert await memory(chat.database) == []
+ # While it answers, the path ends at the owner's message, answered by the new run.
+ waiting = (await thread(chat))["messages"]
+ assert [message["text"] for message in waiting] == ["Book Saturday"] and waiting[0]["run_id"] == retried["run_id"]
+ assert chat.dispatched[-1]["data"]["message"] == "Book Saturday"
+ run = await ledger.get_run(chat.database, retried["run_id"])
+ assert (run.kind, run.user_message_uid, run.parent_run_id) == ("regenerate", first["message_id"], first["run_id"])
+
+ await answer(chat.database, retried["run_id"], "Saturday at 10 is booked.", before=[], after=turn("Book Saturday"))
+ answered = (await thread(chat))["messages"]
+ assert [message["text"] for message in answered] == ["Book Saturday", "Saturday at 10 is booked."]
+ assert answered[1]["siblings"]["count"] == 2 and answered[1]["siblings"]["index"] == 1
+ # Only the latest answer can be tried again.
+ older = answered[1]["siblings"]["ids"][0]
+ assert (await chat.handlers.handle_regenerate_chat_reply({"session_id": "wf", "message_id": older}, None))["error"] == "not_found"
+
+
+async def test_trying_again_a_message_nothing_answered(chat):
+ await talking(chat.database)
+ sent = await chat.handlers.handle_send_chat_message({"message": "Book Saturday", "session_id": "wf"}, None)
+ run = await ledger.start_run(chat.database, run_id=sent["run_id"], **CLAIM)
+ await branches.record_cursor(chat.database, run_id=run.run_id, agent_node_id=AGENT, generation=1, messages=[])
+ await save_conversation(chat.database, workflow_id="wf", generation=1, agent_node_id=AGENT, messages=turn("half"))
+ await ledger.finish_run(chat.database, run_id=run.run_id, success=False, error="boom", **CLAIM)
+ retried = await chat.handlers.handle_regenerate_chat_reply({"session_id": "wf", "message_id": sent["message_id"]}, None)
+ assert retried["success"] is True and retried["message_id"] == sent["message_id"]
+ assert await memory(chat.database) == []
+ assert await path(chat) == ["Book Saturday"]
+
+
+# ----- refusals -------------------------------------------------------------------
+
+
+async def test_a_change_made_meanwhile_or_a_run_answering_refuses_a_move(chat):
+ first = await conversation(chat)
+ stale = await chat.handlers.handle_edit_chat_message(
+ {"session_id": "wf", "message_id": first["message_id"], "message": "x", "expected_revision": 0}, None
+ )
+ assert stale["error"] == "revision_conflict"
+ await chat.handlers.handle_send_chat_message({"message": "And Sunday?", "session_id": "wf"}, None)
+ busy = await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": first["message_id"], "message": "x"}, None)
+ assert busy["error"] == "run_in_progress"
+ # Nothing moved.
+ assert await memory(chat.database) == turn("Book Saturday")
+
+
+async def test_a_memory_that_no_longer_starts_the_same_way_cannot_go_back(chat):
+ await conversation(chat)
+ second = await chat.handlers.handle_send_chat_message({"message": "And Sunday?", "session_id": "wf"}, None)
+ both = turn("Book Saturday") + turn("And Sunday?")
+ await answer(chat.database, second["run_id"], "Sunday too.", before=turn("Book Saturday"), after=both)
+ # Summarized since: the stored conversation no longer starts the way it
+ # did when the second message was answered.
+ summarized = [{"role": "user", "content": "Summary: Saturday is booked."}, *turn("And Sunday?")]
+ await save_conversation(chat.database, workflow_id="wf", generation=1, agent_node_id=AGENT, messages=summarized)
+ refused = await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": second["message_id"], "message": "x"}, None)
+ assert refused["error"] == "cannot_rewind"
+ # Going back to before everything still works: the agent starts over.
+ first_id = (await thread(chat))["messages"][0]["id"]
+ edited = await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": first_id, "message": "Book Sunday"}, None)
+ assert edited["success"] is True and await memory(chat.database) == []
+
+
+async def test_what_cannot_be_edited(chat):
+ first = await conversation(chat)
+ reply = (await thread(chat))["messages"][1]
+ assert (await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": reply["id"], "message": "x"}, None))["error"] == "not_editable"
+ assert (await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": "m_nope", "message": "x"}, None))["error"] == "not_found"
+ assert (await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": first["message_id"], "message": " "}, None))["error"] == "invalid_request"
+ assert (await chat.handlers.handle_edit_chat_message({"session_id": "default", "message_id": first["message_id"], "message": "x"}, None))["error"] == "not_editable"
+ # After a restart, the earlier generation's messages stay as they were.
+ await add_control(chat.database, "wf", "running", generation=2, nodes=[{"id": "wf:chatTrigger:1", "type": "chatTrigger", "data": {}}])
+ older = await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": first["message_id"], "message": "x"}, None)
+ assert older["error"] == "older_generation"
+ assert [message["editable"] for message in (await thread(chat, all_generations=True))["messages"]] == [False, False]
+
+
+async def test_a_version_no_longer_kept_cannot_be_switched_to(chat):
+ from sqlalchemy import delete
+
+ from models.chat import ChatBranchSnapshot
+
+ first = await conversation(chat)
+ edited = await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": first["message_id"], "message": "Book Sunday"}, None)
+ await answer(chat.database, edited["run_id"], "Sunday is booked.", before=[], after=turn("Book Sunday"))
+ async with chat.database.get_session() as session:
+ await session.execute(delete(ChatBranchSnapshot))
+ await session.commit()
+ refused = await chat.handlers.handle_switch_chat_branch({"session_id": "wf", "message_id": first["message_id"]}, None)
+ assert refused["error"] == "branch_unavailable"
+ assert await path(chat) == ["Book Sunday", "Sunday is booked."]
+
+
+# ----- what the part left made ----------------------------------------------------------
+
+
+async def draft(database, approval_id: str, run_id: str, status: str) -> None:
+ from models.approvals import ApprovalRequest
+
+ async with database.get_session() as session:
+ session.add(
+ ApprovalRequest(
+ id=approval_id, idempotency_key=f"k-{approval_id}", owner_id="owner", workflow_id="wf",
+ node_id="wf:whatsappSend:1", kind="tool_call", channel="WhatsApp", action="WhatsApp message",
+ recipient="447700900123", status=status, run_id=run_id, draft_text="Running late",
+ )
+ )
+ await session.commit()
+
+
+async def test_leaving_cancels_waiting_drafts_and_tells_what_went_anyway(chat):
+ from services.approvals import store
+
+ first = await conversation(chat)
+ await draft(chat.database, "ap_wait", first["run_id"], "pending")
+ await draft(chat.database, "ap_sent", first["run_id"], "sent")
+ edited = await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": first["message_id"], "message": "Book Sunday"}, None)
+ assert edited["success"] is True
+ assert (await store.get(chat.database, "ap_wait")).status == "cancelled"
+ assert (await store.get(chat.database, "ap_sent")).status == "sent"
+ claimed = await notes.claim_notes(chat.database, session_id="wf", run_id="r_next")
+ [note] = [item for item in claimed if item.key.startswith("branch:")]
+ assert note.text.startswith("[update]{") and '"result": "sent"' in note.text and "447700900123" in note.text
+
+
+# ----- ratings ------------------------------------------------------------------------
+
+
+async def test_rating_an_answer(chat):
+ await conversation(chat)
+ reply = (await thread(chat))["messages"][1]
+ rated = await chat.handlers.handle_set_chat_feedback({"session_id": "wf", "message_id": reply["id"], "value": "up"}, None)
+ assert rated == {"success": True, "message_id": reply["id"], "value": "up", "reaches": ["next_turn"]}
+ assert (await thread(chat))["messages"][1]["feedback"] == "up"
+ [note] = await notes.claim_notes(chat.database, session_id="wf", run_id="r_next")
+ assert note.key == f"feedback:{reply['id']}" and note.text.startswith('[feedback]{"rating": "good"')
+ taken_back = await chat.handlers.handle_set_chat_feedback({"session_id": "wf", "message_id": reply["id"], "value": None}, None)
+ assert taken_back["reaches"] == [] and (await thread(chat))["messages"][1]["feedback"] is None
+ user = (await thread(chat))["messages"][0]
+ assert (await chat.handlers.handle_set_chat_feedback({"session_id": "wf", "message_id": user["id"], "value": "up"}, None))["error"] == "not_found"
+ assert (await chat.handlers.handle_set_chat_feedback({"session_id": "wf", "message_id": reply["id"], "value": "meh"}, None))["error"] == "invalid_request"
+
+
+async def test_a_rating_listener_adds_where_it_reaches(chat, monkeypatch):
+ from services.chat import feedback
+
+ heard = []
+
+ async def remember(*, database, workflow_id, message, value):
+ heard.append((workflow_id, message["uid"], value))
+ return "memory"
+
+ monkeypatch.setattr(feedback, "_LISTENERS", [])
+ feedback.register_feedback_listener(remember)
+ await conversation(chat)
+ reply = (await thread(chat))["messages"][1]
+ rated = await chat.handlers.handle_set_chat_feedback({"session_id": "wf", "message_id": reply["id"], "value": "down"}, None)
+ assert rated["reaches"] == ["next_turn", "memory"] and heard == [("wf", reply["id"], "down")]
+
+
+async def test_clearing_the_chat_forgets_versions_and_ratings(chat):
+ from sqlmodel import select
+
+ from models.chat import ChatBranchSnapshot, ChatFeedback
+
+ first = await conversation(chat)
+ reply = (await thread(chat))["messages"][1]
+ await chat.handlers.handle_set_chat_feedback({"session_id": "wf", "message_id": reply["id"], "value": "up"}, None)
+ await chat.handlers.handle_edit_chat_message({"session_id": "wf", "message_id": first["message_id"], "message": "Book Sunday"}, None)
+ await chat.database.clear_chat_messages("wf")
+ async with chat.database.get_session() as session:
+ assert (await session.execute(select(ChatBranchSnapshot))).scalars().all() == []
+ assert (await session.execute(select(ChatFeedback))).scalars().all() == []
+
+
[email protected]("value", ["1", True, 1.5])
+async def test_a_revision_must_be_a_number(chat, value):
+ first = await conversation(chat)
+ refused = await chat.handlers.handle_edit_chat_message(
+ {"session_id": "wf", "message_id": first["message_id"], "message": "x", "expected_revision": value}, None
+ )
+ assert refused["error"] == "invalid_request"