Skip to content

Self-improving AI Employees for everyone

18.5 KB
Raw Blame
"""Approval rows (models.approvals.ApprovalRequest): create once per wait or
held call, read, move with a compare-and-swap, cancel, count, delete.

Functions take the ``Database`` and open their own session, like
services.employees.store. They never import ``nodes/``.
"""

from __future__ import annotations

import uuid
from datetime import datetime, timezone
from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple

from sqlalchemy import delete, func, or_, update
from sqlalchemy.exc import IntegrityError
from sqlmodel import select

from models.approvals import ApprovalDecision, ApprovalRequest
from services.approvals.contract import FINAL_STATUSES

#: Fields a row may be created with.
CREATE_FIELDS = frozenset(
    {
        "owner_id",
        "workflow_id",
        "node_id",
        "generation",
        "execution_id",
        "runtime",
        "kind",
        "status",
        "channel",
        "action",
        "recipient",
        "recipient_label",
        "subject",
        "draft_text",
        "final_text",
        "final_subject",
        "context_excerpt",
        "max_length",
        "details",
        "expires_at",
        "node_type",
        "tool_node_id",
        "tool_call_id",
        "agent_node_id",
        "run_id",
        "ui_part_id",
        "node_data",
        "args",
        "original_args",
        "body_field",
        "subject_field",
        "approved_by",
        "decided_at",
        "consumed_at",
        "outcome",
        "outcome_error",
        "outcome_at",
    }
)

#: Rows the owner may still act on, or that are on their way.
_OPEN_CANDIDATES = ("pending", "approved", "sending", "failed", "discarded")


class ApprovalConflict(ValueError):
    """The row moved first (someone else decided, or it expired)."""


def _utcnow() -> datetime:
    return datetime.now(timezone.utc)


def aware(moment: Optional[datetime]) -> Optional[datetime]:
    if moment is None:
        return None
    return moment if moment.tzinfo else moment.replace(tzinfo=timezone.utc)


async def get(database: Any, approval_id: str) -> Optional[ApprovalRequest]:
    async with database.get_session() as session:
        return await session.get(ApprovalRequest, approval_id)


async def get_by_key(database: Any, idempotency_key: str) -> Optional[ApprovalRequest]:
    async with database.get_session() as session:
        result = await session.execute(select(ApprovalRequest).where(ApprovalRequest.idempotency_key == idempotency_key))
        return result.scalar_one_or_none()


async def get_or_create(database: Any, *, idempotency_key: str, fields: Dict[str, Any]) -> Tuple[ApprovalRequest, bool]:
    """The wait's (or the held call's) row: created the first time, found on
    every retry."""
    unknown = set(fields) - CREATE_FIELDS
    if unknown:
        raise ValueError(f"not approval fields: {sorted(unknown)}")
    existing = await get_by_key(database, idempotency_key)
    if existing is not None:
        return existing, False
    values = {"status": "pending", **fields}
    row = ApprovalRequest(id=uuid.uuid4().hex, idempotency_key=idempotency_key, **values)
    try:
        async with database.get_session() as session:
            session.add(row)
            await session.commit()
        return row, True
    except IntegrityError:
        existing = await get_by_key(database, idempotency_key)
        if existing is None:
            raise
        return existing, False


async def transition(
    database: Any,
    approval_id: str,
    *,
    expected_revision: int,
    from_statuses: Sequence[str],
    status: str,
    values: Optional[Dict[str, Any]] = None,
    decision: Optional[Tuple[str, str, str]] = None,
) -> ApprovalRequest:
    """Move a row that is in one of ``from_statuses`` at ``expected_revision``
    to ``status``, if nobody moved it first. ``decision`` (``(decision,
    decision_key, actor)``) is recorded in the same transaction, so a
    decision is kept exactly when it took effect."""
    now = _utcnow()
    changes = {"status": status, "revision": expected_revision + 1, "updated_at": now, **(values or {})}
    async with database.get_session() as session:
        result = await session.execute(
            update(ApprovalRequest)
            .where(
                ApprovalRequest.id == approval_id,
                ApprovalRequest.revision == expected_revision,
                ApprovalRequest.status.in_(tuple(from_statuses)),
            )
            .values(**changes)
        )
        if not result.rowcount:
            await session.rollback()
            raise ApprovalConflict("approval_conflict")
        if decision is not None:
            kind, key, actor = decision
            session.add(ApprovalDecision(approval_id=approval_id, decision=kind, decision_key=key, actor=actor, revision=expected_revision + 1))
        try:
            await session.commit()
        except IntegrityError:
            # The same decision key, recorded by a concurrent request first.
            await session.rollback()
            raise ApprovalConflict("approval_conflict")
    row = await get(database, approval_id)
    assert row is not None
    return row


async def settle(
    database: Any,
    approval_id: str,
    *,
    expected_revision: int,
    status: str,
    values: Optional[Dict[str, Any]] = None,
) -> ApprovalRequest:
    """Move a pending row to a final status (expired, cancelled), if nobody
    moved it first."""
    if status not in FINAL_STATUSES:
        raise ValueError(f"not a final approval status: {status}")
    return await transition(
        database,
        approval_id,
        expected_revision=expected_revision,
        from_statuses=("pending",),
        status=status,
        values={"decided_at": _utcnow(), **(values or {})},
    )


async def find_decision(database: Any, approval_id: str, decision_key: str) -> Optional[ApprovalDecision]:
    async with database.get_session() as session:
        result = await session.execute(
            select(ApprovalDecision).where(ApprovalDecision.approval_id == approval_id, ApprovalDecision.decision_key == decision_key)
        )
        return result.scalar_one_or_none()


def is_open(row: ApprovalRequest, now: Optional[datetime] = None) -> bool:
    """Still the owner's to act on, or on its way: waiting, sent but
    undoable, sending, failed (to retry), or discarded and restorable."""
    now = now or _utcnow()
    if row.status in ("pending", "sending", "failed"):
        return True
    if row.status == "approved":
        return row.consumed_at is None
    if row.status == "discarded":
        restore = aware(row.restore_until)
        return restore is not None and restore > now
    return False


def cancellable(row: ApprovalRequest, now: Optional[datetime] = None, *, failed: bool = False) -> bool:
    """What a Reset, a branch or a deleted run cancels: everything open
    except a send already under way and a failure (nothing left to stop),
    unless ``failed``: clearing a conversation ends its failures too."""
    if row.status == "failed":
        return failed
    return row.status != "sending" and is_open(row, now)


async def cancel_open(
    database: Any,
    *,
    workflow_id: str,
    generation: Optional[int] = None,
    run_ids: Optional[Iterable[str]] = None,
    failed: bool = False,
    runtime: Optional[str] = None,
) -> List[ApprovalRequest]:
    """Cancel a workflow's drafts that still wait (all generations, one, or
    those of some chat runs; only those of one ``runtime``, when given):
    waiting, approved but not handed on yet, or discarded and restorable;
    with ``failed``, failed sends as well."""
    statuses = ("pending", "approved", "discarded", "failed") if failed else ("pending", "approved", "discarded")
    async with database.get_session() as session:
        query = select(ApprovalRequest).where(
            ApprovalRequest.workflow_id == workflow_id,
            ApprovalRequest.status.in_(statuses),
        )
        if generation is not None:
            query = query.where(ApprovalRequest.generation == generation)
        if runtime is not None:
            query = query.where(ApprovalRequest.runtime == runtime)
        if run_ids is not None:
            ids = [run_id for run_id in run_ids if run_id]
            if not ids:
                return []
            query = query.where(ApprovalRequest.run_id.in_(ids))
        rows = list((await session.execute(query)).scalars().all())
    now = _utcnow()
    cancelled: List[ApprovalRequest] = []
    for row in rows:
        if not cancellable(row, now, failed=failed):
            continue
        try:
            cancelled.append(
                await transition(
                    database,
                    row.id,
                    expected_revision=row.revision,
                    from_statuses=(row.status,),
                    status="cancelled",
                    values={"decided_at": now, "grace_until": None, "restore_until": None},
                )
            )
        except ApprovalConflict:
            continue
    return cancelled


async def cancel_pending(database: Any, *, workflow_id: str, generation: Optional[int] = None) -> List[ApprovalRequest]:
    """Older name for :func:`cancel_open`."""
    return await cancel_open(database, workflow_id=workflow_id, generation=generation)


async def list_approvals(
    database: Any,
    *,
    owner_id: Optional[str] = None,
    workflow_id: Optional[str] = None,
    status: Optional[str] = None,
    statuses: Optional[Sequence[str]] = None,
    run_id: Optional[str] = None,
    kind: Optional[str] = None,
    ids: Optional[Sequence[str]] = None,
    decision_key: Optional[str] = None,
    limit: int = 50,
) -> List[ApprovalRequest]:
    """Newest first. ``decision_key``: the rows whose latest decision had it."""
    query = select(ApprovalRequest)
    if owner_id is not None:
        query = query.where(ApprovalRequest.owner_id == owner_id)
    if workflow_id is not None:
        query = query.where(ApprovalRequest.workflow_id == workflow_id)
    if status is not None:
        query = query.where(ApprovalRequest.status == status)
    if statuses is not None:
        query = query.where(ApprovalRequest.status.in_(tuple(statuses)))
    if run_id is not None:
        query = query.where(ApprovalRequest.run_id == run_id)
    if kind is not None:
        query = query.where(or_(ApprovalRequest.kind == kind, ApprovalRequest.kind.is_(None)) if kind == "gate" else ApprovalRequest.kind == kind)
    if ids is not None:
        query = query.where(ApprovalRequest.id.in_(tuple(ids)))
    if decision_key is not None:
        query = query.where(ApprovalRequest.decision_key == decision_key)
    query = query.order_by(ApprovalRequest.created_at.desc()).limit(max(1, min(int(limit), 100)))
    async with database.get_session() as session:
        return list((await session.execute(query)).scalars().all())


async def list_open(database: Any, *, owner_id: Optional[str] = None, workflow_id: Optional[str] = None, limit: int = 50) -> List[ApprovalRequest]:
    """What the owner may still act on (``is_open``), newest first."""
    rows = await list_approvals(database, owner_id=owner_id, workflow_id=workflow_id, statuses=_OPEN_CANDIDATES, limit=100)
    now = _utcnow()
    return [row for row in rows if is_open(row, now)][: max(1, min(int(limit), 100))]


async def pending_counts(database: Any, workflow_ids: Iterable[str]) -> Dict[str, int]:
    """Drafts waiting for the owner, per workflow."""
    ids = [str(workflow_id) for workflow_id in workflow_ids if workflow_id]
    if not ids:
        return {}
    async with database.get_session() as session:
        result = await session.execute(
            select(ApprovalRequest.workflow_id, func.count())
            .where(ApprovalRequest.workflow_id.in_(ids), ApprovalRequest.status == "pending")
            .group_by(ApprovalRequest.workflow_id)
        )
        return {workflow_id: int(count) for workflow_id, count in result.all()}


async def list_pending(database: Any) -> List[ApprovalRequest]:
    async with database.get_session() as session:
        result = await session.execute(select(ApprovalRequest).where(ApprovalRequest.status == "pending"))
        return list(result.scalars().all())


async def list_unread_waits(database: Any) -> List[ApprovalRequest]:
    """Decided rows a turn waits on whose wait has not taken the answer yet
    (services/approvals/waiting.py)."""
    async with database.get_session() as session:
        result = await session.execute(
            select(ApprovalRequest).where(
                ApprovalRequest.runtime == "turn",
                ApprovalRequest.status != "pending",
                ApprovalRequest.consumed_at.is_(None),
            )
        )
        return list(result.scalars().all())


async def list_unfinished_sends(database: Any) -> List[ApprovalRequest]:
    """Approved held calls not handed on, and sends that never reported."""
    async with database.get_session() as session:
        result = await session.execute(
            select(ApprovalRequest).where(ApprovalRequest.kind == "tool_call", ApprovalRequest.status.in_(("approved", "sending")))
        )
        return list(result.scalars().all())


async def delete_for_workflow(database: Any, workflow_id: str) -> int:
    async with database.get_session() as session:
        ids = select(ApprovalRequest.id).where(ApprovalRequest.workflow_id == workflow_id)
        await session.execute(delete(ApprovalDecision).where(ApprovalDecision.approval_id.in_(ids)))
        result = await session.execute(delete(ApprovalRequest).where(ApprovalRequest.workflow_id == workflow_id))
        await session.commit()
        return int(result.rowcount or 0)


def _iso(moment: Optional[datetime]) -> Optional[str]:
    moment = aware(moment)
    return moment.isoformat() if moment is not None else None


#: What the card of a tool with no spec says once it ran, and when it did not.
DONE_OUTCOME = ("Done", "Not done")


def _spec_of(row: ApprovalRequest) -> Any:
    from services.node_registry import get_node_class
    from services.plugin.approval import approval_spec

    return approval_spec(get_node_class(row.node_type)) if row.node_type else None


def _outcome_labels(row: ApprovalRequest) -> Tuple[str, str]:
    """What the card says once it went, and when it did not: a held tool
    call's plugin words it (its ``approval`` spec); a gate's draft is a
    message; a tool with no spec did something."""
    from services.plugin.approval import MESSAGE_OUTCOME

    if row.kind != "tool_call":
        return MESSAGE_OUTCOME
    spec = _spec_of(row)
    return spec.outcome_labels if spec is not None else DONE_OUTCOME


def approval_class(row: ApprovalRequest) -> Optional[str]:
    """What a held call may do (services/approvals/classes.py): the card's
    pill, and whether it may offer an always-allow rule."""
    from services.approvals.classes import call_data, class_of
    from services.node_registry import get_node_class

    node_cls = get_node_class(row.node_type) if row.node_type else None
    if node_cls is None:
        return None
    return class_of(node_cls, call_data(node_cls, row.node_data or {}, row.args), tool_call=bool(row.tool_call_id))


def summary(row: ApprovalRequest, *, deployment_state: Optional[str] = None, now: Optional[datetime] = None) -> Dict[str, Any]:
    """What a card shows for one row (``ApprovalSummary``,
    docs-internal/chat_protocol.md)."""
    now = now or _utcnow()
    decided = row.status in ("approved", "sending", "sent", "failed")
    kind = row.kind or "gate"
    out: Dict[str, Any] = {
        "approval_id": row.id,
        "workflow_id": row.workflow_id,
        "node_id": row.node_id,
        "kind": kind,
        "status": row.status,
        "channel": row.channel,
        "channel_label": row.channel,
        "recipient": row.recipient,
        "recipient_label": row.recipient_label or row.recipient,
        "body": (row.final_text if decided and row.final_text is not None else row.draft_text),
        "created_at": _iso(row.created_at),
        "expires_at": _iso(row.expires_at),
        "revision": row.revision,
        "max_length": row.max_length,
        "editable": row.status == "pending" and (kind == "gate" or bool(row.body_field)),
        "details": [dict(item) for item in (row.details or []) if isinstance(item, dict)],
    }
    sent, failed = _outcome_labels(row)
    out["outcome_labels"] = {"sent": sent, "failed": failed}
    if kind == "tool_call":
        from services.approvals import allows

        klass = approval_class(row)
        out["approval_class"] = klass
        # A tool with no spec: the card shows what it runs with, not a message.
        out["generic"] = _spec_of(row) is None
        # Its turn waits on it: no Undo, and the employee gets the real result.
        out["waits"] = row.runtime == "turn"
        scope = allows.offer(row, klass)
        out["always"] = None if scope is None else {"label": scope.label, "scope": scope.kind}
    if row.action:
        out["action"] = row.action
    subject = row.final_subject if decided and row.final_subject else row.subject
    if subject:
        out["subject"] = subject
    if row.context_excerpt:
        out["context_excerpt"] = row.context_excerpt
    if row.approved_by:
        out["approved_by"] = row.approved_by
    if row.note:
        out["note"] = row.note
    if row.edited:
        out["edited"] = True
    grace = aware(row.grace_until)
    if row.status == "approved" and row.consumed_at is None and grace is not None:
        out["undo_until"] = grace.isoformat()
    restore = aware(row.restore_until)
    if row.status == "discarded" and restore is not None and restore > now:
        out["restore_until"] = restore.isoformat()
    if row.consumed_at is not None:
        out["consumed_at"] = _iso(row.consumed_at)
    if row.outcome:
        outcome: Dict[str, Any] = {"certainty": row.outcome}
        if row.outcome_error:
            outcome["error"] = row.outcome_error
        if row.outcome_at:
            outcome["at"] = _iso(row.outcome_at)
        out["outcome"] = outcome
    for key in ("run_id", "tool_call_id", "ui_part_id", "agent_node_id"):
        value = getattr(row, key, None)
        if value:
            out[key] = value
    if deployment_state:
        out["deployment_state"] = deployment_state
    return out


__all__ = [
    "ApprovalConflict",
    "approval_class",
    "aware",
    "cancel_open",
    "cancel_pending",
    "cancellable",
    "delete_for_workflow",
    "find_decision",
    "get",
    "get_by_key",
    "get_or_create",
    "is_open",
    "list_approvals",
    "list_open",
    "list_pending",
    "list_unfinished_sends",
    "pending_counts",
    "settle",
    "summary",
    "transition",
]