Skip to content

Self-improving AI Employees for everyone

43.5 KB
Raw Blame
"""Chat's WebSocket commands (docs-internal/chat_protocol.md).

Moved here from ``routers/websocket.py`` with the run runtime. Every command
that names a session checks the socket first (``services/chat/access.py``).

``send_chat_message`` saves the owner's message and dispatches it to the
workflow's chat triggers. A workflow's session takes a message only while
its deployment would read it (``delivery``: ``"now"`` while it runs,
``"queued"`` while it is paused); otherwise nothing is saved and the answer
is ``not_running``. When a deployed chat trigger will answer the session,
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, Mapping, Optional, Tuple

from fastapi import WebSocket

from core.container import container
from core.logging import get_logger
from services.chat import branches, choice, ledger, reducer
from services.chat.access import ChatAccessDenied, authorize_session, session_id_of
from services.chat.attachments import MAX_ATTACHMENTS, AttachmentRefused, check_attachments
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 (
    DEFAULT_SESSION,
    announce_chat_updated,
    chat_execution_id,
    clear_chat_session,
    delivery_for,
    record_chat_message,
)
from services.ws_handler_registry import ws_handler

logger = get_logger(__name__)

PROTOCOL_VERSION = 2
_DENIED = {"success": False, "error": "access_denied"}
#: A workflow's chat messages travel through Temporal (``dispatch.emit``
#: signals its listeners) and only a Temporal activity claims their runs, so
#: a send while it is unreachable would be lost.
_UNAVAILABLE = {"success": False, "error": "engine_unavailable"}


def _engine_connected() -> bool:
    """Whether Temporal is reachable now (the flag ``/health/ready`` reads)."""
    try:
        wrapper = container.temporal_client()
    except Exception:  # noqa: BLE001 - not wired: nothing can deliver
        return False
    return bool(wrapper is not None and wrapper.is_connected)


def _wire_run(run: Any) -> Dict[str, Any]:
    """The run a message started or answers, as a message carries it: enough
    to show how it ended after a reload (a failed run leaves no reply), what
    the employee did on the way and how long it took."""
    wire: Dict[str, Any] = {"run_id": run.run_id, "state": run.state, "outcome": run.outcome}
    if run.state == "error":
        wire["error"] = {"message": run.error, "code": run.error_code}
        hint = (run.result or {}).get("hint")
        if hint:
            wire["error"]["hint"] = hint
    if run.steps:
        wire["steps"] = [dict(step) for step in run.steps]
    if run.started_at and run.finished_at:
        started = run.started_at if run.started_at.tzinfo else run.started_at.replace(tzinfo=timezone.utc)
        finished = run.finished_at if run.finished_at.tzinfo else run.finished_at.replace(tzinfo=timezone.utc)
        wire["duration_ms"] = max(0, int((finished - started).total_seconds() * 1000))
    return wire


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"),
        "role": row.get("role"),
        "kind": row.get("kind") or "text",
        "text": row.get("message"),
        "message": row.get("message"),
        "timestamp": row.get("timestamp"),
        "run_key": row.get("execution_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": 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(run_id or "")
    if run is not None:
        wire["run"] = _wire_run(run)
    return wire


async def run_snapshots(database: Any, session_id: str) -> List[Dict[str, Any]]:
    """Snapshots of a session's live runs. The hub is read before the rows,
    so an event published in between carries a newer ``seq`` than the
    snapshot and still reaches a subscriber."""
    hub = get_chat_hub()
    live = hub.session_live(session_id)
    rows = await ledger.live_runs(database, session_id)
    return [await _run_snapshot(database, run, live.get(run.run_id), hub.epoch) for run in rows]


async def _run_snapshot(database: Any, run: Any, live: Any, hub_epoch: str) -> Dict[str, Any]:
    snapshot = {**reducer.merge_snapshot(reducer.snapshot_from_row(run), live), "hub_epoch": hub_epoch}
    control = await ledger.owning_control(database, run)
    if ledger.controlled_generation(control):
        from services.deployment.control import serialize_control

        snapshot["workflow_control"] = serialize_control(control)
    return snapshot


async def _thread_state(database: Any, session_id: str) -> Dict[str, Any]:
    from models.chat import ChatThread

    async with database.get_session() as session:
        thread = await session.get(ChatThread, session_id)
    return {
        "active_leaf_id": thread.active_leaf_uid if thread is not None else None,
        "revision": thread.revision if thread is not None else 0,
    }


async def _answers_session(database: Any, control: Any, session_id: str) -> bool:
    """Whether a chat trigger in the deployed graph accepts this session, so
    a run started for the message will be picked up. Decided from the
    trigger's own filter (``event_waiter.build_filter``), never from a node
    type name."""
    from services import event_waiter

    graph = getattr(control, "graph_snapshot", None) or {}
    for node in graph.get("nodes") or []:
        node_type = str(node.get("type") or "")
        config = event_waiter.get_trigger_config(node_type)
        if config is None or config.event_type != MESSAGE_WIRE_ROUTING_KEY:
            continue
        if (node.get("data") or {}).get("disabled"):
            continue
        params = await database.get_node_parameters(str(node.get("id") or "")) or {}
        try:
            if event_waiter.build_filter(node_type, params)({"session_id": session_id, "message": ""}):
                return True
        except Exception:  # noqa: BLE001 - a broken filter admits, as the listener's does
            return True
    return False


async def _ui_event(database: Any, session_id: str, raw: Any) -> Dict[str, Any]:
    """A button press, checked against the interface it came from. Returns
    ``{label, meta, prompt}``; raises ``ValueError`` saying why not."""
    from services.chat import parts

    if not isinstance(raw, dict):
        raise ValueError("ui_event is {part_id, element_id, action, params}")
    part_id = raw.get("part_id")
    part = await parts.find_ui_part(database, session_id, part_id) if isinstance(part_id, str) and part_id else None
    if part is None:
        raise ValueError("this chat has no such interface")
    try:
        pressed = parts.check_ui_event(part, raw.get("element_id"), raw.get("action"), raw.get("params"))
    except parts.UiRefused as exc:
        raise ValueError(str(exc)) from None
    event = {"part_id": part_id, "element_id": raw["element_id"], "action": raw["action"], "params": pressed["params"]}
    label = pressed["label"] or str(raw["action"])
    return {
        "label": label,
        "meta": {"ui_event": event},
        "prompt": parts.ui_event_message(label=label, **event),
    }


async def _dispatch(
    session_id: str,
    workflow_id: Optional[str],
    *,
    message_uid: str,
    prompt: str,
    run_id: Optional[str],
    timestamp: str,
    attachments: Optional[List[Dict[str, Any]]] = None,
) -> 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.
    Without a tracked run, the saved message supplies a stable event identity.
    Its attachments ride along (the trigger's output carries them)."""
    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
    if attachments:
        event_data["attachments"] = list(attachments)
    await dispatch_chat_message_received(event_data, workflow_id=workflow_id, event_id=run_id or message_uid)
    logger.info("Chat message dispatched", session_id=session_id, run_id=run_id)


def _decline_key(session_id: str, client_message_id: Any) -> str:
    """The decision key a message declines waiting calls under: its message
    id, so the same message sent again finds what it declined."""
    from uuid import uuid4

    from services.approvals.waiting import message_key

    try:
        return message_key(ledger.client_message_uid(session_id, client_message_id))
    except ValueError:
        return message_key(f"m_{uuid4().hex}")


def _declined(rows: List[Any], timestamp: str, delivery: Optional[str]) -> Dict[str, Any]:
    """The answer to a message that declined the calls its run waited on."""
    response: Dict[str, Any] = {
        "success": True,
        "timestamp": timestamp,
        "message_id": None,
        "run_id": None,
        "declined": {"run_id": rows[0].run_id, "approval_ids": [row.id for row in rows]},
    }
    if delivery is not None:
        response["delivery"] = delivery
    return response


# ``message`` is checked below: a message may be only files.
@ws_handler()
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
    ``{message_id, run_id, delivery, timestamp}``; ``run_in_progress`` (with
    the live ``run_id``), ``not_running``, ``engine_unavailable`` (Temporal is
    unreachable, nothing saved), ``save_failed``, ``access_denied``,
    ``invalid_request`` or ``ui_event_rejected`` otherwise.

    With ``ui_event`` the message is a button pressed in an interface the
    employee showed: checked against that interface, saved as the owner's
    message reading the button's label (kind ``action``), and sent to the
    employee as a ``[ui-event]`` line naming the press.

    ``attachments`` are files the chat uploaded under the workspace's
    ``uploads/`` (``services/chat/attachments.py``: rebuilt from the files,
    at most six; refused with ``attachment_rejected``); a message may be
    only files. ``options.web: false`` keeps the employee off web search for
    this message.

    While the session's run waits on the owner's answer to a call its turn
    holds, a plain message (no ``ui_event``, no files) answers that call:
    it declines it, the message its note (RFC-0007 D3,
    ``services/approvals/waiting.py``), saves no message, starts no run and
    answers ``{message_id: null, run_id: null, declined: {run_id,
    approval_ids}, delivery}``. Sent again, it answers the same."""
    message = data.get("message")
    raw_attachments = data.get("attachments")
    if not isinstance(message, str) or not (message.strip() or raw_attachments):
        return {"success": False, "error": "invalid_request", "detail": "message must be text"}
    if data.get("role", "user") != "user":
        return {"success": False, "error": "invalid_request", "detail": "send_chat_message sends the owner's messages"}
    session_id = session_id_of(data)
    timestamp = data.get("timestamp") or datetime.now(timezone.utc).isoformat()
    database = container.database()
    try:
        scope = await authorize_session(database, websocket, session_id)
    except ChatAccessDenied:
        return dict(_DENIED)

    attachments: List[Dict[str, Any]] = []
    if raw_attachments:
        if scope.workflow_id is None:
            return {"success": False, "error": "invalid_request", "detail": "files can be attached only in a workflow's chat"}
        try:
            attachments = await check_attachments(database, scope.workflow_id, raw_attachments)
        except AttachmentRefused as exc:
            return {"success": False, "error": "attachment_rejected", "detail": str(exc)}

    press: Optional[Dict[str, Any]] = None
    if data.get("ui_event") is not None:
        try:
            press = await _ui_event(database, session_id, data["ui_event"])
        except ValueError as exc:
            return {"success": False, "error": "ui_event_rejected", "detail": str(exc)}
        message = press["label"]

    # The scope rides the envelope's ``workflow_id``, so ``dispatch.emit``
    # signals only this workflow's listeners (without it one workflow's chat
    # fired every deployed chat trigger). The editor's "default" session
    # keeps its unscoped delivery.
    control = None
    delivery: Optional[str] = None
    if scope.workflow_id is not None:
        control = await database.get_latest_workflow_control(session_id)
        delivery = delivery_for(control)
        if delivery is None:
            return {"success": False, "error": "not_running"}
        if not _engine_connected():
            return dict(_UNAVAILABLE)
    track = scope.workflow_id is not None and await _answers_session(database, control, session_id)
    try:
        options = await _run_options(database, websocket, data.get("options")) if track else {}
    except choice.ChoiceRefused as exc:
        return {"success": False, "error": "model_unavailable", "detail": exc.detail}
    except ValueError as exc:
        return {"success": False, "error": "invalid_request", "detail": str(exc)}

    decline_key = None
    if scope.workflow_id is not None and press is None and not attachments:
        from services.approvals.waiting import declined_with

        decline_key = _decline_key(session_id, data.get("client_message_id"))
        earlier = await declined_with(database, decline_key)
        if earlier:
            return _declined(earlier, timestamp, delivery)
    try:
        admission = await ledger.admit_message(
            database,
            session_id=session_id,
            workflow_id=scope.workflow_id,
            execution_id=chat_execution_id(control) if scope.workflow_id is not None else None,
            text=message,
            track=track,
            state="queued" if delivery == "queued" else "pending",
            kind="action" if press is not None else "message",
            message_kind="action" if press is not None else "text",
            client_message_id=data.get("client_message_id"),
            meta=press["meta"] if press is not None else None,
            options=options,
            attachments=attachments or None,
        )
    except ledger.RunInProgress as exc:
        if decline_key is not None:
            from services.approvals.waiting import decline_with_message
            from services.authz.ws_surface import execution_principal

            declined = await decline_with_message(
                database, run_id=exc.run.run_id, owner=execution_principal({}, websocket), message=message, decision_key=decline_key
            )
            if declined:
                return _declined(declined, timestamp, delivery)
        return {"success": False, "error": "run_in_progress", "run_id": exc.run.run_id}
    except ValueError as exc:
        return {"success": False, "error": "invalid_request", "detail": str(exc)}
    except Exception:
        logger.warning("Chat message could not be saved", session_id=session_id, exc_info=True)
        return {"success": False, "error": "save_failed"}

    row, run = admission.message, admission.run
    if admission.created:
        # Sent before open threads hear of it, so this answer, which
        # registers the run with the sender, reaches the sender before their
        # thread reads the run: told first, their thread showed it live and
        # asked for it (get_chat_run). Sending never raises (emit is
        # fail-soft), so threads always hear of it.
        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,
            attachments=attachments,
        )
        await announce_chat_updated(session_id, "user")

    response: Dict[str, Any] = {
        "success": True,
        "message": "Chat message sent",
        "timestamp": timestamp,
        "message_id": row["uid"],
        "run_id": run.run_id if run is not None else None,
    }
    if delivery is not None:
        response["delivery"] = delivery
    return response


@ws_handler()
async def handle_get_chat_messages(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    """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:
        scope = await authorize_session(database, websocket, session_id)
    except ChatAccessDenied:
        return dict(_DENIED)
    try:
        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)
    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,
                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,
    }


@ws_handler()
async def handle_chat_subscribe(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    """Send the session's run events to this socket from now on. Answers
    the hub's epoch and the live runs' snapshots; events after a snapshot
    carry a higher ``seq`` than it."""
    session_id = session_id_of(data)
    database = container.database()
    try:
        await authorize_session(database, websocket, session_id)
    except ChatAccessDenied:
        return dict(_DENIED)
    hub = get_chat_hub()
    hub.subscribe(websocket, session_id)
    try:
        active_runs = await run_snapshots(database, session_id)
    except Exception:
        logger.warning("Chat runs could not be read", session_id=session_id, exc_info=True)
        return {"success": False, "error": "read_failed", "session_id": session_id, "hub_epoch": hub.epoch}
    return {"success": True, "session_id": session_id, "hub_epoch": hub.epoch, "active_runs": active_runs}


@ws_handler()
async def handle_chat_unsubscribe(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    """Stop sending the session's run events to this socket."""
    session_id = session_id_of(data)
    hub = get_chat_hub()
    hub.unsubscribe(websocket, session_id)
    return {"success": True, "session_id": session_id, "hub_epoch": hub.epoch}


@ws_handler("run_id")
async def handle_get_chat_run(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    """One run's snapshot, live or ended."""
    database = container.database()
    run = await ledger.get_run(database, str(data["run_id"]))
    if run is None:
        return {"success": False, "error": "not_found"}
    try:
        await authorize_session(database, websocket, run.session_id)
    except ChatAccessDenied:
        return dict(_DENIED)
    hub = get_chat_hub()
    live = hub.live_snapshot(run.run_id)
    run = await ledger.get_run(database, run.run_id) or run
    return {"success": True, "run": await _run_snapshot(database, run, live, hub.epoch)}


@ws_handler("run_id")
async def handle_stop_chat_run(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    """Suspend a controlled run's generation; retain legacy terminal Stop."""
    database = container.database()
    run = await ledger.get_run(database, str(data["run_id"]))
    if run is None:
        return {"success": False, "error": "not_found"}
    try:
        await authorize_session(database, websocket, run.session_id)
    except ChatAccessDenied:
        return dict(_DENIED)
    control = await ledger.owning_control(database, run)
    if ledger.controlled_generation(control):
        if run.state not in ledger.LIVE_STATES:
            return {"success": False, "error": "not_stoppable", "run_id": run.run_id, "state": run.state}
        if not isinstance(data.get("idempotency_key"), str) or not data["idempotency_key"].strip():
            return {"success": False, "error": "idempotency_key_required"}
        from services.deployment.handlers import handle_pause_workflow

        result = await handle_pause_workflow(
            {
                "workflow_id": control.workflow_id,
                "expected_root_execution_id": run.run_key,
                "expected_revision": data.get("expected_revision"),
                "idempotency_key": data.get("idempotency_key"),
            },
            websocket,
        )
        return {**result, "run_id": run.run_id, "resumable": True}
    run = await ledger.request_stop(database, run.run_id) or run
    if run.state not in ("stopping", "stopped"):
        return {"success": False, "error": "not_stoppable", "run_id": run.run_id, "state": run.state}
    return {"success": True, "run_id": run.run_id, "state": run.state}


@ws_handler("part_id")
async def handle_chat_ui_state(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    """What the owner set in an interface the employee showed
    (``changes: [{path, value}]``, the last value per path winning). Kept on
    the reply (``parts.ui[].state``), so a reload shows it, and told to the
    employee at the start of its next turn (a ``[ui-state]`` note,
    ``services/chat/notes.py``). Answers the state's new ``state_revision``;
    ``not_found`` when the session has no such interface,
    ``invalid_request`` for a change that does not fit."""
    from services.chat import notes, parts

    session_id = session_id_of(data)
    database = container.database()
    try:
        await authorize_session(database, websocket, session_id)
    except ChatAccessDenied:
        return dict(_DENIED)
    part_id = str(data["part_id"])
    try:
        updated = await parts.update_ui_state(database, session_id, part_id, data.get("changes"))
    except parts.UiRefused as exc:
        return {"success": False, "error": "invalid_request", "detail": str(exc)}
    if updated is None:
        return {"success": False, "error": "not_found"}
    try:
        await notes.upsert_note(
            database,
            session_id=session_id,
            key=f"ui-state:{part_id}",
            kind="ui-state",
            text=parts.ui_state_message(part_id=part_id, state=updated["state"]),
        )
    except Exception:  # noqa: BLE001 - the state is saved and shows; only the note is lost
        logger.warning("The employee could not be told what the owner set", part_id=part_id, exc_info=True)
    return {"success": True, "part_id": part_id, "state_revision": updated["state_revision"]}


async def _run_options(database: Any, websocket: WebSocket, raw: Any) -> Dict[str, Any]:
    """The per-message choices kept on the run: ``web``, and the model and
    effort the owner picked (services/chat/choice.py)."""
    from services.authz.ws_surface import execution_principal

    return await choice.run_options(database, container.auth_service(), raw, principal=execution_principal({}, websocket))


@ws_handler()
async def handle_get_chat_context(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    """What the session's message box offers: slash commands (the generic
    ones in ``chat_defaults.json`` and those its employee's apps add,
    ``employee_apps.json``; ``{name}`` is the workflow's name), whether files
    can be attached (a workflow's chat), whether the Web chip has web search
    to turn off (a search tool in the saved graph), and the limits."""
    from services.chat.config import load_chat_config
    from services.employees.apps import app_for_node_type
    from services.media.limits import MEDIA_MAX_UPLOAD_BYTES
    from services.node_registry import get_node_class

    session_id = session_id_of(data)
    database = container.database()
    try:
        scope = await authorize_session(database, websocket, session_id)
    except ChatAccessDenied:
        return dict(_DENIED)
    saved = await database.get_workflow(scope.workflow_id) if scope.workflow_id is not None else None
    graph = (getattr(saved, "data", None) or {}) if saved is not None else {}
    name = str(getattr(saved, "name", "") or "the employee")
    node_types = [str(node.get("type") or "") for node in graph.get("nodes") or [] if isinstance(node, dict)]

    configured = (load_chat_config().get("commands") or {}).get("generic") or []
    commands: List[Dict[str, Any]] = []
    seen: set = set()

    def add(command: Any) -> None:
        if not isinstance(command, dict) or command.get("command") in seen or not scope.workflow_id:
            return
        seen.add(command.get("command"))
        commands.append(
            {
                "command": str(command.get("command")),
                "description": str(command.get("description") or "").replace("{name}", name),
                "fill": str(command.get("fill") or "").replace("{name}", name),
                "suggest": bool(command.get("suggest")),
            }
        )

    for node_type in node_types:
        app = app_for_node_type(node_type)
        for command in app.commands if app is not None else ():
            add(dict(command))
    for command in configured:
        add(command)

    def searches(node_type: str) -> bool:
        cls = get_node_class(node_type)
        return cls is not None and "search" in tuple(getattr(cls, "group", ()) or ())

    return {
        "success": True,
        "session_id": session_id,
        "commands": commands,
        "capabilities": {
            "attachments": scope.workflow_id is not None,
            "web": any(searches(t) for t in node_types),
            "model_choice": scope.workflow_id is not None and _takes_model_choice(graph),
        },
        "limits": {"max_attachments": MAX_ATTACHMENTS, "max_upload_bytes": MEDIA_MAX_UPLOAD_BYTES},
    }


def _takes_model_choice(graph: Mapping[str, Any]) -> bool:
    """Whether the agent that answers the owner applies the model picker's
    choice: it runs as an AgentWorkflow, whose prepare step reads the run's
    options (``prepare_agent_payload``). A Claude Code or RLM agent, or any
    agent while the agent workflow is off, never does."""
    from core.config import Settings
    from services.employees.talk import talk_state
    from services.temporal.workflow import AGENT_WORKFLOW_TYPES

    agent = talk_state(graph).agent_node_id
    if agent is None or not Settings().temporal_agent_workflow_enabled:
        return False
    for node in graph.get("nodes") or []:
        if isinstance(node, dict) and node.get("id") == agent:
            return str(node.get("type") or "") in AGENT_WORKFLOW_TYPES
    return False


@ws_handler()
async def handle_get_chat_models(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    """The model picker for a workflow's chat (services/chat/choice.py):
    ``{auto, models, efforts}``. Each row is ``{id, name, short, description,
    effort, effort_note, available, reason}``; the owner's choice is in their
    settings. Refused for ``"default"``."""
    from services.authz.ws_surface import execution_principal

    session_id = session_id_of(data)
    database = container.database()
    try:
        scope = await authorize_session(database, websocket, session_id)
    except ChatAccessDenied:
        return dict(_DENIED)
    if scope.workflow_id is None:
        return {"success": False, "error": "invalid_request", "detail": "the model picker belongs to a workflow's chat"}
    saved = await database.get_workflow(scope.workflow_id)
    graph = (getattr(saved, "data", None) or {}) if saved is not None else {}
    picker = await choice.list_models(
        database,
        container.auth_service(),
        principal=execution_principal({}, websocket),
        graph=graph,
        name=str(getattr(saved, "name", "") or "the employee"),
    )
    return {"success": True, "session_id": session_id, **picker}


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"}, {}
        if not _engine_connected():
            return dict(_UNAVAILABLE), {}
        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,
    send the message to the chat triggers, then tell open threads."""
    await branches.after_move(database, moved)
    message, run = moved.result["message"], moved.result["run"]
    # Sent first, as a new message is (handle_send_chat_message).
    await _dispatch(
        moved.session_id,
        moved.workflow_id,
        message_uid=message["uid"],
        prompt=moved.result["prompt"],
        run_id=run.run_id,
        timestamp=timestamp,
        attachments=list(message.get("attachments") or []),
    )
    await announce_chat_updated(moved.session_id, role)
    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
    try:
        options = await _run_options(database, websocket, data.get("options"))
    except choice.ChoiceRefused as exc:
        return {"success": False, "error": "model_unavailable", "detail": exc.detail}
    except ValueError as exc:
        return {"success": False, "error": "invalid_request", "detail": str(exc)}
    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,
            options=options,
        )
    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:
        options = await _run_options(database, websocket, data.get("options"))
    except choice.ChoiceRefused as exc:
        return {"success": False, "error": "model_unavailable", "detail": exc.detail}
    except ValueError as exc:
        return {"success": False, "error": "invalid_request", "detail": str(exc)}
    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"],
            options=options,
        )
    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``, the
    employee's next turn; none for a rating taken back); ``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
    workflow's session the agent forgets the conversation too
    (``services.chat_thread.clear_chat_session``)."""
    session_id = session_id_of(data)
    database = container.database()
    try:
        await authorize_session(database, websocket, session_id)
    except ChatAccessDenied:
        return dict(_DENIED)
    count = await clear_chat_session(database, session_id)
    return {"success": True, "message": f"Cleared {count} chat messages", "cleared_count": count}


@ws_handler("message", "role")
async def handle_save_chat_message(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    """Save one message with the given role, without dispatching it."""
    role = data["role"]
    if role not in ("user", "assistant"):
        return {"success": False, "error": "invalid_request", "detail": "role is user or assistant"}
    session_id = session_id_of(data)
    database = container.database()
    try:
        await authorize_session(database, websocket, session_id)
    except ChatAccessDenied:
        return dict(_DENIED)
    saved = await record_chat_message(database, session_id, role, data["message"])
    return {"success": bool(saved), "message": "Chat message saved" if saved else "Failed to save chat message"}


WS_HANDLERS = {
    "send_chat_message": handle_send_chat_message,
    "get_chat_messages": handle_get_chat_messages,
    "chat_subscribe": handle_chat_subscribe,
    "chat_unsubscribe": handle_chat_unsubscribe,
    "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,
    "get_chat_context": handle_get_chat_context,
    "get_chat_models": handle_get_chat_models,
    "clear_chat_messages": handle_clear_chat_messages,
    "save_chat_message": handle_save_chat_message,
}

__all__ = ["DEFAULT_SESSION", "PROTOCOL_VERSION", "WS_HANDLERS", "run_snapshots"]