Skip to content

Self-improving AI Employees for everyone

16.7 KB
Raw Blame
"""The owner's side of approvals: see drafts, decide them, and the Ask first
rule (docs-internal/chat_protocol.md, "Approvals").

``list_approvals {workflow_id?, status?, run_id?, kind?, limit <= 100}`` ->
``{approvals: ApprovalSummary[], counts: {workflow_id: pending}, server_time}``.
``status`` is a row status, ``open`` (what the owner may still act on, or is
on its way) or ``recent`` (everything, newest first); default ``pending``.

``get_approvals {approval_ids: [...]}`` -> ``{approvals, server_time}``.

``decide_approval {approval_id, decision, decision_key, text?, subject?,
confirm?, note?, always?}`` -> ``{approval, idempotent?, will_send_on_resume}``.
Decisions: ``send`` (``always``: and save the card's always-allow rule),
``undo``, ``discard`` (with the owner's ``note``), ``restore``, ``retry``,
``dismiss`` (services/approvals/decisions.py).
Sending a held tool call starts its send (services/approvals/execution.py),
unless its agent's turn waits on it (``runtime: turn``) and runs it itself.
Errors: ``already_decided``,
``expired``, ``cancelled``, ``too_late``, ``confirm_required``,
``approval_conflict``, ``send_unavailable``, ``not_found``,
``invalid_request``.

``get_ask_first {workflow_id}`` -> ``{ask_first, mode, revision}`` (both
null for a workflow with no rule). ``set_ask_first {workflow_id, ask_first |
mode, expected_revision?}`` -> ``{ask_first, mode, revision, replies_gated,
needs_apply}``; ``rule_conflict`` when it moved. ``mode`` is ``outside``,
``everything`` or ``money_only`` (services/approvals/rules.py): setting it
keeps Ask first in step, and setting Ask first makes the mode follow it.

Always-allow rules (services/approvals/allows.py): ``list_approval_allows
{workflow_id}`` -> ``{allows, money}``, the rules and the money switches of
the employee's tools (``{node_type, operation, label, allow_id}``, the rule
that switches each on or null); ``add_approval_allow {workflow_id,
node_type, operation?}`` -> ``{allow}``, a money switch only;
``remove_approval_allow {workflow_id, allow_id}``.

Only the owner's own drafts and workflows are visible; any other id reads as
not found.
"""

from __future__ import annotations

from datetime import datetime, timezone
from typing import Any, Dict, List

from fastapi import WebSocket

from core.logging import get_logger
from services.approvals import allows, decisions, execution, rules, store, waiter
from services.approvals.contract import APPROVAL_KINDS
from services.approvals.listeners import change_of, notify_approval_changed
from services.approvals.reconcile import reconcile_once
from services.authz.ws_surface import execution_principal
from services.plugin.ws import ws_response

logger = get_logger(__name__)

MAX_LIST = 100
_ROW_STATUSES = ("pending", "approved", "sending", "sent", "failed", "discarded", "expired", "cancelled")
#: The lifecycle stage each decision announces.
_STAGES = {"send": "decided", "discard": "decided", "undo": "undone", "restore": "restored", "retry": "decided", "dismiss": "cancelled"}


def _now() -> str:
    return datetime.now(timezone.utc).isoformat()


async def _deployment_state(database: Any, workflow_id: str) -> str | None:
    try:
        control = await database.get_latest_workflow_control(workflow_id)
    except Exception:
        return None
    return getattr(control, "status", None)


async def _summaries(database: Any, rows: List[Any]) -> List[Dict[str, Any]]:
    states: Dict[str, Any] = {}
    out = []
    for row in rows:
        if row.workflow_id not in states:
            states[row.workflow_id] = await _deployment_state(database, row.workflow_id)
        out.append(store.summary(row, deployment_state=states[row.workflow_id]))
    return out


def _limit(data: Dict[str, Any]) -> int:
    try:
        return max(1, min(int(data.get("limit") or 50), MAX_LIST))
    except (TypeError, ValueError):
        return 50


@ws_response
async def handle_list_approvals(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    from core.container import container

    database = container.database()
    await reconcile_once(database)
    owner = execution_principal(data, websocket)
    workflow_id = str(data.get("workflow_id") or "").strip() or None
    run_id = str(data.get("run_id") or "").strip() or None
    kind = data.get("kind") if data.get("kind") in APPROVAL_KINDS else None
    status = data.get("status")
    limit = _limit(data)
    if status == "open":
        rows = await store.list_open(database, owner_id=owner, workflow_id=workflow_id, limit=limit)
        rows = [row for row in rows if (run_id is None or row.run_id == run_id) and (kind is None or (row.kind or "gate") == kind)]
    else:
        filters: Dict[str, Any] = {}
        if status in _ROW_STATUSES:
            filters["status"] = status
        elif status != "recent":
            filters["status"] = "pending"
        rows = await store.list_approvals(database, owner_id=owner, workflow_id=workflow_id, run_id=run_id, kind=kind, limit=limit, **filters)
    counts: Dict[str, int] = {}
    for row in rows:
        if row.status == "pending":
            counts[row.workflow_id] = counts.get(row.workflow_id, 0) + 1
    return {"success": True, "approvals": await _summaries(database, rows), "counts": counts, "server_time": _now()}


@ws_response
async def handle_get_approvals(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    from core.container import container

    ids = data.get("approval_ids")
    if not isinstance(ids, list) or not ids or len(ids) > MAX_LIST:
        return {"success": False, "error": "invalid_request"}
    database = container.database()
    owner = execution_principal(data, websocket)
    rows = await store.list_approvals(database, owner_id=owner, ids=[str(item) for item in ids], limit=MAX_LIST)
    return {"success": True, "approvals": await _summaries(database, rows), "server_time": _now()}


_RESTORED_FIELDS = (
    "grace_until",
    "decided_at",
    "approved_by",
    "final_text",
    "final_subject",
    "edited",
    "args",
    "node_data",
    "claim_token",
    "consumed_at",
    "outcome",
    "outcome_error",
    "outcome_at",
)


async def _start_or_revert(database: Any, row: Any, original: Any) -> Any:
    """Start a held call's send; put the row back as it was when nothing
    can send it."""
    try:
        await execution.start_send(row)
        return row
    except Exception as exc:
        logger.warning("Could not start a send", approval_id=row.id, error=str(exc))
        try:
            reverted = await store.transition(
                database,
                row.id,
                expected_revision=row.revision,
                from_statuses=("approved",),
                status=original.status,
                values={name: getattr(original, name) for name in _RESTORED_FIELDS},
            )
            await notify_approval_changed(change_of(reverted, "undone"))
        except store.ApprovalConflict:
            pass
        raise execution.SendUnavailable("send_unavailable") from exc


@ws_response
async def handle_decide_approval(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    from core.container import container

    approval_id = str(data.get("approval_id") or "").strip()
    decision = data.get("decision")
    decision_key = str(data.get("decision_key") or "").strip()[:128]
    if not approval_id or decision not in decisions.DECISIONS or not decision_key:
        return {"success": False, "error": "invalid_request"}
    database = container.database()
    owner = execution_principal(data, websocket)
    row = await store.get(database, approval_id)
    if row is None or row.owner_id != owner:
        return {"success": False, "error": "not_found", "approval_id": approval_id}
    try:
        decided, idempotent = await decisions.apply(
            database,
            row,
            decision=decision,
            decision_key=decision_key,
            actor=owner,
            text=data.get("text"),
            subject=data.get("subject"),
            confirm=bool(data.get("confirm")),
            note=data.get("note"),
            always=data.get("always") is True,
        )
    except decisions.DecisionRefused as refused:
        current = await store.get(database, approval_id) or row
        out: Dict[str, Any] = {"success": False, "error": refused.code, "approval": store.summary(current)}
        if refused.detail:
            out["detail"] = refused.detail
        return out
    if idempotent:
        return {"success": True, "idempotent": True, "approval": store.summary(decided), "will_send_on_resume": False}
    waiter.notify(decided.id)
    await notify_approval_changed(change_of(decided, _STAGES.get(decision, "decided")))
    if decided.status == "discarded":
        await execution.tell_employee(database, decided)
    if (decided.kind or "gate") == "tool_call" and decision in ("send", "retry") and decided.runtime != "turn":
        try:
            decided = await _start_or_revert(database, decided, row)
        except execution.SendUnavailable:
            current = await store.get(database, approval_id) or decided
            return {
                "success": False,
                "error": "send_unavailable",
                "detail": "Nothing can send it right now. Try again in a moment.",
                "approval": store.summary(current),
            }
    state = await _deployment_state(database, decided.workflow_id)
    logger.info("Draft decided", approval_id=decided.id, workflow_id=decided.workflow_id, decision=decision, status=decided.status)
    return {
        "success": True,
        "approval": store.summary(decided, deployment_state=state),
        # Nothing a stopped employee approved goes before Resume
        # (execution.send_state); a manual run's draft is not held.
        "will_send_on_resume": decided.status == "approved" and (decided.generation or 0) > 0 and state in execution.STOPPED_STATES,
    }


async def _authorize_workflow(database: Any, websocket: Any, workflow_id: str) -> bool:
    from services.chat.access import ChatAccessDenied, authorize_session

    try:
        await authorize_session(database, websocket, workflow_id)
    except ChatAccessDenied:
        return False
    return True


@ws_response
async def handle_get_ask_first(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    from core.container import container

    workflow_id = str(data.get("workflow_id") or "").strip()
    if not workflow_id:
        return {"success": False, "error": "invalid_request"}
    database = container.database()
    if not await _authorize_workflow(database, websocket, workflow_id):
        return {"success": False, "error": "not_found"}
    rule = await rules.get_rule(database, workflow_id)
    return {
        "success": True,
        "workflow_id": workflow_id,
        "ask_first": None if rule is None else bool(rule.ask_first),
        "mode": None if rule is None else rules.mode_of(rule),
        "revision": 0 if rule is None else rule.revision,
    }


@ws_response
async def handle_set_ask_first(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    from core.container import container

    workflow_id = str(data.get("workflow_id") or "").strip()
    value = data.get("ask_first")
    mode = data.get("mode")
    known_mode = isinstance(mode, str) and mode in rules.ASKS
    if not workflow_id or (mode is None and not isinstance(value, bool)) or (mode is not None and not known_mode):
        return {"success": False, "error": "invalid_request"}
    expected = data.get("expected_revision")
    if expected is not None and not isinstance(expected, int):
        return {"success": False, "error": "invalid_request"}
    database = container.database()
    if not await _authorize_workflow(database, websocket, workflow_id):
        return {"success": False, "error": "not_found"}
    try:
        if mode is not None:
            rule = await rules.set_mode(database, workflow_id, mode, expected_revision=expected)
        else:
            rule = await rules.set_ask_first(database, workflow_id, value, expected_revision=expected)
    except rules.RuleConflict as conflict:
        current = conflict.rule
        return {
            "success": False,
            "error": "rule_conflict",
            "ask_first": None if current is None else bool(current.ask_first),
            "mode": None if current is None else rules.mode_of(current),
            "revision": 0 if current is None else current.revision,
        }
    effects = await rules.notify_rule_changed(database, workflow_id, rule)
    logger.info("Ask first changed", workflow_id=workflow_id, ask_first=rule.ask_first, mode=rule.mode)
    return {
        "success": True,
        "workflow_id": workflow_id,
        "ask_first": bool(rule.ask_first),
        "mode": rules.mode_of(rule),
        "revision": rule.revision,
        "replies_gated": bool(effects.get("replies_gated", False)),
        "needs_apply": bool(effects.get("needs_apply", False)),
    }


async def _authorized(data: Dict[str, Any], websocket: Any) -> Any:
    """The workflow a rules command names, or None when the caller may not
    see it."""
    from core.container import container

    workflow_id = str(data.get("workflow_id") or "").strip()
    database = container.database()
    if not workflow_id or not await _authorize_workflow(database, websocket, workflow_id):
        return None
    return workflow_id


@ws_response
async def handle_list_approval_allows(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    from core.container import container

    workflow_id = await _authorized(data, websocket)
    if workflow_id is None:
        return {"success": False, "error": "not_found"}
    database = container.database()
    found = await allows.list_for_workflow(database, workflow_id)
    switches = {(row.node_type, row.operation): row.id for row in found if row.scope_kind in ("tool", "operation")}
    money = [
        {**option, "allow_id": switches.get((option["node_type"], option["operation"]))}
        for option in await allows.money_options(database, workflow_id)
    ]
    return {"success": True, "workflow_id": workflow_id, "allows": [allows.serialize(row) for row in found], "money": money}


@ws_response
async def handle_add_approval_allow(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    from core.container import container

    workflow_id = await _authorized(data, websocket)
    if workflow_id is None:
        return {"success": False, "error": "not_found"}
    database = container.database()
    node_type, operation = data.get("node_type"), data.get("operation") or ""
    option = next(
        (item for item in await allows.money_options(database, workflow_id) if (item["node_type"], item["operation"]) == (node_type, operation)),
        None,
    )
    if option is None:
        return {"success": False, "error": "invalid_request"}
    scope = allows.Scope(node_type, operation, "operation" if operation else "tool", "", option["label"])
    row = await allows.add(database, workflow_id, scope, created_by=execution_principal(data, websocket))
    logger.info("Always allowed", workflow_id=workflow_id, node_type=node_type, operation=operation)
    return {"success": True, "allow": allows.serialize(row)}


@ws_response
async def handle_remove_approval_allow(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
    from core.container import container

    workflow_id = await _authorized(data, websocket)
    if workflow_id is None:
        return {"success": False, "error": "not_found"}
    if not await allows.remove(container.database(), workflow_id, str(data.get("allow_id") or "")):
        return {"success": False, "error": "not_found"}
    logger.info("Removed an always-allow rule", workflow_id=workflow_id, allow_id=data.get("allow_id"))
    return {"success": True}


async def on_workflow_deleted(database: Any, workflow_id: str) -> None:
    removed = await store.delete_for_workflow(database, workflow_id)
    await rules.delete_rule(database, workflow_id)
    await allows.delete_for_workflow(database, workflow_id)
    if removed:
        logger.info("Removed a deleted workflow's drafts", workflow_id=workflow_id, count=removed)


WS_HANDLERS: Dict[str, Any] = {
    "list_approvals": handle_list_approvals,
    "get_approvals": handle_get_approvals,
    "decide_approval": handle_decide_approval,
    "get_ask_first": handle_get_ask_first,
    "set_ask_first": handle_set_ask_first,
    "list_approval_allows": handle_list_approval_allows,
    "add_approval_allow": handle_add_approval_allow,
    "remove_approval_allow": handle_remove_approval_allow,
}


__all__ = [
    "WS_HANDLERS",
    "handle_add_approval_allow",
    "handle_decide_approval",
    "handle_get_approvals",
    "handle_get_ask_first",
    "handle_list_approval_allows",
    "handle_list_approvals",
    "handle_remove_approval_allow",
    "handle_set_ask_first",
    "on_workflow_deleted",
]