Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

47.7 KB
Raw Blame
"""Decisions API — the approve/reject/edit surface for gated Executive proposals.

This is the approve→execute bridge: proposals written by calendar_tools (and
future classes) sit in the trust ledger as `status='proposed'` until a human
acts here. What approving, rejecting and cancelling DO is per class: each class
resolved here has a ``DecisionClassSpec`` in ``DECISION_CLASSES`` (meeting
booking: create the calendar event on approve, delete it on cancel). An
instance of any other class is refused with 409, never carried out as some
other class.

Routes:
  GET  /decisions            — list instances (filter by class, status)
  GET  /decisions/{id}       — single instance detail
  POST /decisions/{id}/approve — approve (optionally with edited payload)
  POST /decisions/{id}/reject  — reject
  GET  /decisions/classes/meeting_scheduling — the class's autonomy mode
  PUT  /decisions/classes/meeting_scheduling — set it (principal only)
  GET  /audit/reliability    — per-class reliability card (also in audit.py router)
"""
from __future__ import annotations

import json
import logging
from collections.abc import Awaitable, Callable
from dataclasses import dataclass
from types import SimpleNamespace
from typing import Any, Literal

from fastapi import APIRouter, HTTPException, Request
from pydantic import BaseModel

from openexecutive.api import caller as api_caller
from openexecutive.memory.decision_ledger import (
    DECISION_ALERT_SOURCE,
    STATUS_APPROVED_UNCHANGED,
    STATUS_APPROVED_WITH_EDIT,
    STATUS_FAILED,
    STATUS_PROPOSED,
    STATUS_REJECTED,
    DecisionInstance,
    ReliabilityCard,
    aggregate_reliability,
    get_class_mode,
    get_decision_instance,
    list_instances,
    mark_resolved,
    mark_reversed,
    set_class_mode,
)

router = APIRouter()
logger = logging.getLogger(__name__)

_CALENDAR_CLASS = "meeting_scheduling"


# ---------------------------------------------------------------------------
# Request / response models
# ---------------------------------------------------------------------------

class ApproveBody(BaseModel):
    """Approve a proposal, optionally with an edited meeting payload.

    Any field present in `edits` overwrites the corresponding field in the
    original proposed_payload.  Missing fields retain their proposed values.
    Supported edit keys: title, start, end, attendee_emails, description.

    For a reply card (``delegation_reply``) nothing is edited here: the draft
    is sent as it is in Gmail. ``edits`` carries the person's second yes when
    something changed since the card was made: ``recipients`` (the list they
    were shown) and ``thread_moved_on: true``, and ``seen_caught_up_at``
    (the card's ``caught_up_at`` as shown, so a draft brought up to date
    since asks again); and Send + allow in training:
    ``allow: true``, with ``example: true`` to keep an edited draft as an
    example (``delegation.training``).

    For a meeting invite card (``delegation_invite``): ``answer``, ``accept``
    (the default) or ``decline``, answered in the person's own calendar; and
    ``allow: true`` with accept, in training, to accept that sender's
    invites on their own from now on (``delegation.invites``).
    """
    edits: dict[str, Any] | None = None


class RejectBody(BaseModel):
    reason: str = ""


ClassMode = Literal["propose", "auto_execute"]


class DecisionClassMode(BaseModel):
    """How the Executive handles a decision class: ``propose`` puts each one
    on the briefing for approval, ``auto_execute`` does it straight away."""
    decision_class: str
    mode: ClassMode


class DecisionClassModeUpdate(BaseModel):
    mode: ClassMode


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------

def _parse_payload(instance: DecisionInstance) -> dict[str, Any]:
    try:
        return json.loads(instance.proposed_payload_json)
    except (json.JSONDecodeError, TypeError):
        return {}


def _payload_diff(original: dict[str, Any], final: dict[str, Any]) -> bool:
    """Return True if the payloads differ in any semantically meaningful field."""
    for key in ("title", "start", "end", "description"):
        if original.get(key) != final.get(key):
            return True
    orig_attendees = sorted(original.get("attendee_emails", []))
    final_attendees = sorted(final.get("attendee_emails", []))
    return orig_attendees != final_attendees


def _clear_decision_alert(
    instance_id: int, status: str, source: str | None = DECISION_ALERT_SOURCE
) -> None:
    """Clear the companion briefing alert when a decision is resolved.

    Calendar proposals are surfaced on the briefing as an alert linked by
    ``external_id='decision:{id}'`` (see calendar_tools._propose_via_decision_alert).
    Transition it out of the unread queue when the decision is approved
    (``ack``) or rejected/cancelled (``dismissed``). Best-effort: a missing
    alert (e.g. a decision created before the bridge) is a harmless no-op, and
    a failure here must not 500 a decision that already executed. ``source``
    is the class's ``alert_source``; a class that raises no alert passes None.
    """
    if source is None:
        return
    from openexecutive.alerts.store import set_status_by_external
    from openexecutive.memory.decision_ledger import decision_alert_external_id

    try:
        set_status_by_external(source, decision_alert_external_id(instance_id), status)
    except Exception:
        logger.exception(
            "decisions: failed to clear companion alert for instance %d", instance_id
        )


async def _execute_booking(
    instance: DecisionInstance,
    final_payload: dict[str, Any],
    *,
    by_principal: bool = False,
) -> dict[str, Any]:
    """Call the MCP to create the calendar event. Returns the gateway response.

    ``by_principal``: the approver is the principal, acting in the web app. An
    approval runs outside any chat turn, so without this the gateway would
    refuse a contact on the invite even though the principal asked for it.
    """
    from openexecutive.orchestrator.calendar_tools import _do_create_event
    from openexecutive.orchestrator.mcp_gateway import get_active_gateway
    from openexecutive.orchestrator.people_tools import grant_contact_egress

    gateway = get_active_gateway()
    if gateway is None:
        return {"error": "MCP gateway not running — cannot create calendar event"}
    if by_principal:
        with grant_contact_egress():
            return await _do_create_event(gateway, final_payload)
    return await _do_create_event(gateway, final_payload)


def _approver_is_principal(request: Request) -> bool:
    """Whether the caller resolves to the principal (a request with no
    ``x-caller-email`` does — the CLI, direct curl, local login). Fails
    closed."""
    from openexecutive.api.routes.people import caller_is_principal

    return caller_is_principal(request)


def _is_private(instance: DecisionInstance) -> bool:
    """Not everyone's to see: a class that is the principal's alone
    (``DecisionClassSpec.principal_only``) or its approver's alone
    (``approver_only``, decided before this is asked), or a payload marked
    ``private`` (a booking with one of the principal's contacts, per
    ``calendar_tools``)."""
    spec = DECISION_CLASSES.get(instance.decision_class)
    if spec is not None and (spec.principal_only or spec.approver_only):
        return True
    payload = _parse_payload(instance)
    return payload.get("private") is True


def _approver_only(instance: DecisionInstance) -> bool:
    spec = DECISION_CLASSES.get(instance.decision_class)
    return spec is not None and spec.approver_only


def _principal_and_approver(instance: DecisionInstance) -> bool:
    spec = DECISION_CLASSES.get(instance.decision_class)
    return spec is not None and spec.principal_and_approver


def _caller_is_approver(instance: DecisionInstance, request: Request) -> bool:
    """Whether the caller is the person ``instance`` went to for approval.
    Fails closed."""
    from openexecutive.api.routes.chat import _resolve_caller_person_id

    try:
        caller = _resolve_caller_person_id(request)
    except Exception:
        logger.exception("decisions: caller lookup failed — treating them as someone else")
        return False
    return caller is not None and caller == instance.approver_person_id


def _visible_instance(instance_id: int, request: Request) -> DecisionInstance:
    """The instance, or 404 — also for a private one when the caller is not
    the principal, and for one only its approver may see when the caller is
    anyone else (the principal included), so its existence (and the contact
    or mail on it) is not revealed."""
    instance = get_decision_instance(instance_id)
    if instance is None:
        raise HTTPException(status_code=404, detail="Decision instance not found")
    if _approver_only(instance):
        if not _caller_is_approver(instance, request):
            raise HTTPException(status_code=404, detail="Decision instance not found")
        return instance
    if _principal_and_approver(instance):
        if not (_approver_is_principal(request) or _caller_is_approver(instance, request)):
            raise HTTPException(status_code=404, detail="Decision instance not found")
        return instance
    if _is_private(instance) and not _approver_is_principal(request):
        raise HTTPException(status_code=404, detail="Decision instance not found")
    return instance


_NOT_YOURS = (
    "Only the person this went to for approval, or the owner, can decide it."
)


def _resolver(instance: DecisionInstance, request: Request) -> int | None:
    """The caller's Person id when they may approve, reject or cancel
    ``instance``: the principal, or the person it went to for approval
    (``approver_person_id``) unless it is private to the principal. Anyone
    else gets 403. Fails closed: a roster that can't be read is a 403."""
    from openexecutive.api.routes.chat import _resolve_caller_person_id

    caller = _resolve_caller_person_id(request)
    if _approver_only(instance):
        if caller is not None and caller == instance.approver_person_id:
            return caller
    elif _approver_is_principal(request):
        return caller
    elif _principal_and_approver(instance):
        if caller is not None and caller == instance.approver_person_id:
            return caller
    elif caller is not None and caller == instance.approver_person_id and not _is_private(instance):
        return caller
    logger.info(
        "decisions: caller may not resolve instance %d (class %s)",
        instance.id, instance.decision_class,
    )
    raise HTTPException(status_code=403, detail=_NOT_YOURS)


def _refresh(instance_id: int) -> DecisionInstance:
    updated = get_decision_instance(instance_id)
    if updated is None:
        raise HTTPException(status_code=500, detail="Instance vanished after update")
    return updated


# ---------------------------------------------------------------------------
# Decision classes
# ---------------------------------------------------------------------------

# (instance, body, request, the resolver's Person id) → the updated instance.
_Approve = Callable[
    [DecisionInstance, ApproveBody, Request, int | None], Awaitable[DecisionInstance]
]


@dataclass(frozen=True)
class DecisionClassSpec:
    """How the routes below handle one class of gated decision."""

    name: str
    # Only the principal may see or resolve any instance of it, whatever its
    # payload says.
    principal_only: bool
    # The companion briefing alert's source, cleared when an instance is
    # resolved; None when the class raises none.
    alert_source: str | None
    # Carries out an approval and records it (its own compare-and-set, with
    # the resolver); raises HTTPException to refuse. Called only on a
    # 'proposed' instance, and only for a caller who may resolve it.
    approve: _Approve
    # Best effort, after a reject has been recorded.
    after_reject: Callable[[DecisionInstance], Awaitable[None]] | None = None
    # Undoes what an approval did; None when it can't be undone (409).
    cancel: Callable[[DecisionInstance], Awaitable[None]] | None = None
    # Only the person an instance went to for approval (``approver_person_id``)
    # may see or resolve it — not the principal either, unless it is theirs.
    approver_only: bool = False
    # Only the principal and the person it went to for approval may see or
    # resolve it; nobody else on the team, whatever its payload says.
    principal_and_approver: bool = False


def _spec_for(instance: DecisionInstance) -> DecisionClassSpec:
    spec = DECISION_CLASSES.get(instance.decision_class)
    if spec is None:
        raise HTTPException(
            status_code=409,
            detail=f"Decisions of class {instance.decision_class!r} can't be resolved here.",
        )
    return spec


# ---------------------------------------------------------------------------
# Routes
# ---------------------------------------------------------------------------

@router.get("/decisions", response_model=list[DecisionInstance])
def get_decisions(
    request: Request,
    decision_class: str = _CALENDAR_CLASS,
    status: str | None = None,
    limit: int = 50,
) -> list[DecisionInstance]:
    if limit < 1 or limit > 500:
        raise HTTPException(status_code=400, detail="limit must be 1–500")
    spec = DECISION_CLASSES.get(decision_class)
    if spec is not None and (spec.approver_only or (spec.principal_and_approver and not _approver_is_principal(request))):
        from openexecutive.api.routes.chat import _resolve_caller_person_id

        caller = _resolve_caller_person_id(request)
        if caller is None:
            return []
        instances = list_instances(decision_class, status=status, limit=500)
        return [i for i in instances if i.approver_person_id == caller][:limit]
    if _approver_is_principal(request):
        return list_instances(decision_class, status=status, limit=limit)
    spec = DECISION_CLASSES.get(decision_class)
    if spec is not None and spec.principal_only:
        return []
    instances = list_instances(decision_class, status=status, limit=limit)
    return [i for i in instances if not _is_private(i)]


@router.get("/decisions/{instance_id}", response_model=DecisionInstance)
def get_decision(instance_id: int, request: Request) -> DecisionInstance:
    return _visible_instance(instance_id, request)


def _check_booking_edits(payload: dict[str, Any], edits: dict[str, Any]) -> None:
    """An edited booking keeps the shape the tool would have accepted: an
    edited title of 1-200 characters, and a start and end it can read (naive
    times count as UTC, as in ``calendar_tools._parse_iso``), end after start.
    422 otherwise."""
    from openexecutive.orchestrator.calendar_tools import _parse_iso

    if "title" in edits:
        title = edits["title"]
        if not isinstance(title, str) or not title.strip() or len(title) > 200:
            raise HTTPException(status_code=422, detail="Give the meeting a title of up to 200 characters.")
    raw_start, raw_end = payload.get("start"), payload.get("end")
    start = _parse_iso(raw_start) if isinstance(raw_start, str) else None
    end = _parse_iso(raw_end) if isinstance(raw_end, str) else None
    if start is None or end is None:
        raise HTTPException(status_code=422, detail="Start and end must be dates and times.")
    if end <= start:
        raise HTTPException(status_code=422, detail="The end has to be after the start.")


async def _approve_booking(
    instance: DecisionInstance, body: ApproveBody, request: Request, resolver: int | None
) -> DecisionInstance:
    """Meeting booking: create the calendar event, then record the approval."""
    return await _book(instance, body, by_principal=_approver_is_principal(request), resolver=resolver)


async def _book(
    instance: DecisionInstance, body: ApproveBody, *, by_principal: bool, resolver: int | None
) -> DecisionInstance:
    """Book ``instance``'s meeting and record the approval. Contacts go on
    the invite only when ``by_principal``."""
    instance_id = instance.id
    original_payload = _parse_payload(instance)
    final_payload = dict(original_payload)

    # Apply edits if provided.
    if body.edits:
        for key in ("title", "start", "end", "description"):
            if key in body.edits:
                final_payload[key] = body.edits[key]
        _check_booking_edits(final_payload, body.edits)
        if "attendee_emails" in body.edits:
            final_payload["attendee_emails"] = body.edits["attendee_emails"]

    # Re-run the backend's conflict check — advisory here, but we log a
    # warning if the slot is busy. (Google: multi-calendar freebusy; Microsoft:
    # the Executive's own calendar view — see integrations.workspace.)
    try:
        from openexecutive.integrations.workspace.registry import get_calendar_provider
        from openexecutive.orchestrator.mcp_gateway import get_active_gateway
        gw = get_active_gateway()
        if gw is not None:
            busy = await get_calendar_provider().has_conflicts(
                gw,
                final_payload["start"],
                final_payload["end"],
                list(final_payload.get("attendee_emails", [])),
            )
            if busy:
                logger.warning(
                    "decisions/approve: calendar reports conflict for instance %d — proceeding anyway (human override)",
                    instance_id,
                )
    except Exception:
        logger.debug("decisions/approve: conflict check skipped", exc_info=True)

    # Create the actual calendar event. Contacts on the invite only when the
    # principal is the one approving.
    result = await _execute_booking(instance, final_payload, by_principal=by_principal)
    if "error" in result:
        raise HTTPException(status_code=502, detail=result["error"])

    external_event_id = result.get("event_id")
    # Persist the video-meeting link (Meet or Teams, if one was minted) so the
    # UI and any later reference can surface it.
    if result.get("meet_link"):
        final_payload["meet_link"] = result["meet_link"]
    edited = _payload_diff(original_payload, final_payload)
    outcome = STATUS_APPROVED_WITH_EDIT if edited else STATUS_APPROVED_UNCHANGED

    # Compare-and-set: if a concurrent approve already won, our event is a
    # duplicate and must be deleted before we return 409.
    recorded = mark_resolved(
        instance_id,
        outcome,
        final_payload=final_payload,
        resolver_person_id=resolver,
        external_event_id=external_event_id,
    )
    if not recorded:
        # A concurrent approve beat us.  Delete the event we just created to
        # avoid a ghost booking with no ledger row referencing it.
        if external_event_id:
            try:
                from openexecutive.orchestrator.calendar_tools import _do_delete_event
                gw2 = get_active_gateway()
                if gw2 is not None:
                    await _do_delete_event(gw2, external_event_id)
            except Exception:
                logger.exception(
                    "decisions/approve: failed to clean up leaked event %s for instance %d",
                    external_event_id, instance_id,
                )
        raise HTTPException(
            status_code=409,
            detail="A concurrent approval already processed this proposal.",
        )

    # Won the compare-and-set: clear the companion briefing alert.
    _clear_decision_alert(instance_id, "ack")
    return _refresh(instance_id)


async def _cancel_booking(instance: DecisionInstance) -> None:
    """Meeting booking: delete the event an approval created, if any."""
    if not instance.external_event_id:
        if instance.status == STATUS_PROPOSED:
            return
        # Booked, but the event id was never read: refuse rather than report
        # a cancel that leaves the meeting on everyone's calendar.
        from openexecutive.orchestrator.calendar_tools import _NO_EVENT_ID

        raise HTTPException(status_code=409, detail=_NO_EVENT_ID)
    from openexecutive.orchestrator.calendar_tools import _do_delete_event
    from openexecutive.orchestrator.mcp_gateway import get_active_gateway

    gw = get_active_gateway()
    if gw is None:
        raise HTTPException(status_code=502, detail="MCP gateway not running")
    result = await _do_delete_event(gw, instance.external_event_id)
    if "error" in result:
        raise HTTPException(status_code=502, detail=result["error"])


_MEETING_BOOKING = DecisionClassSpec(
    name=_CALENDAR_CLASS,
    principal_only=False,
    alert_source=DECISION_ALERT_SOURCE,
    approve=_approve_booking,
    cancel=_cancel_booking,
)


async def _send_reply(
    instance: DecisionInstance, body: ApproveBody, request: Request, resolver: int | None
) -> DecisionInstance:
    """Send the reply's exact Gmail draft, on its person's tap
    (``delegation.reply_send``, which checks everything again first)."""
    from openexecutive.delegation.reply_send import SendRefused, send_approved_reply

    # Send + allow, in training: ``edits.allow``; ``edits.example`` keeps an
    # edited draft as how they write (Drafts in training). The rest is the
    # second yes.
    confirm = dict(body.edits or {})
    allow = confirm.pop("allow", None)
    example = confirm.pop("example", None)
    try:
        await send_approved_reply(
            instance, caller=api_caller.caller(request), resolver=resolver, confirm=confirm,
            allow=allow is True, example=example is True,
        )
    except SendRefused as refused:
        raise HTTPException(
            status_code=refused.status,
            detail={"code": refused.code, "message": refused.message, **refused.extra},
        ) from None
    return _refresh(instance.id)


async def _dismiss_reply(instance: DecisionInstance) -> None:
    """Delete the reply's draft from Gmail when nobody edited it."""
    from openexecutive.delegation.replies import dismiss

    await dismiss(instance)


# A reply the inbox watcher drafted as someone (delegation.inbox): theirs
# alone, whatever its payload says (a team member's is hidden from the
# principal too), and never an alert.
_DELEGATED_REPLY = DecisionClassSpec(
    name="delegation_reply",
    principal_only=False,
    approver_only=True,
    alert_source=None,
    approve=_send_reply,
    after_reject=_dismiss_reply,
)

async def _carry_out_lead(
    instance: DecisionInstance, body: ApproveBody, request: Request, resolver: int | None
) -> DecisionInstance:
    """Take the lead: do the exact action that waited, once (claimed first),
    then record it in Recent activity.

    ``edits.input`` changes the card's editable fields first (the message,
    a meeting's title or time; ``take_the_lead.apply_edits``). ``edits.allow``
    on a training card also allows that action from now on, keeping any
    edit as an example of how it's wanted: the principal's alone, and only
    from a request the API can tie to them, like turning Take the lead on."""
    from openexecutive.memory.decision_ledger import claim_for_execution, finish_execution
    from openexecutive.orchestrator import take_the_lead

    payload = _parse_payload(instance)
    edits = body.edits or {}
    changed: dict[str, str] = {}
    if edits.get("input") is not None:
        # Changing what the Executive says or books is the principal's: an
        # area approver says yes or no to what it would do, as it stands.
        if not _approver_is_principal(request):
            raise HTTPException(status_code=403, detail="Only the account owner can change this before approving.")
        source: dict[str, Any] = payload["input"] if isinstance(payload.get("input"), dict) else {}
        try:
            new_input, changed = take_the_lead.apply_edits(
                str(payload.get("tool") or ""), source, edits["input"], mcp=bool(payload.get("mcp")),
            )
        except take_the_lead.EditError as exc:
            raise HTTPException(status_code=422, detail=str(exc)) from None
        payload = {**payload, "input": new_input}
    grant = payload.get("allow") if isinstance(payload.get("allow"), dict) else None
    allowing = edits.get("allow") is True
    if allowing:
        if grant is None or payload.get("kind") != take_the_lead.TRAINING:
            raise HTTPException(status_code=422, detail="This one can't be allowed from its card.")
        if not _approver_is_principal(request) or not _provably_principal(request):
            raise HTTPException(
                status_code=403,
                detail="Only the account owner can allow this, from a signed-in session on this server.",
            )
        # Checked before anything is done, so a full list refuses the allow
        # instead of failing after the action went out.
        if not take_the_lead.room_for(str(grant.get("key"))):
            raise HTTPException(
                status_code=409,
                detail=f"It can learn at most {take_the_lead.ALLOWED_MAX} things. Remove one in Settings first.",
            )
    if not claim_for_execution(instance.id, resolver_person_id=resolver):
        raise HTTPException(status_code=409, detail="Someone else resolved this decision first.")
    try:
        result = await take_the_lead.carry_out(payload, by_principal=_approver_is_principal(request))
    except Exception as exc:
        logger.exception("decisions/approve: Take the lead action %d failed", instance.id)
        finish_execution(instance.id, STATUS_FAILED, final_payload={**payload, "error": type(exc).__name__})
        take_the_lead.resolved(instance.id, "failed")
        _clear_decision_alert(instance.id, "dismissed")
        raise HTTPException(status_code=502, detail="Something went wrong, so it may not have gone through. Check before trying again.") from None
    failed = take_the_lead.result_failed(result)
    finish_execution(
        instance.id,
        STATUS_FAILED if failed else STATUS_APPROVED_WITH_EDIT if changed else STATUS_APPROVED_UNCHANGED,
        final_payload={**payload, "result": result[:2000]},
    )
    take_the_lead.resolved(instance.id, "failed" if failed else "approved")
    _clear_decision_alert(instance.id, "dismissed" if failed else "ack")
    if failed:
        raise HTTPException(status_code=502, detail=f"It couldn't do that: {result[:300]}")
    if allowing and grant is not None:
        try:
            take_the_lead.allow(
                str(grant.get("key")), str(grant.get("label") or ""), example=changed or None,
                created_by=f"person:{resolver}" if resolver is not None else "principal", decision_id=instance.id,
            )
        except take_the_lead.RuleError:
            # It's done; only the learning failed (the list filled up since
            # the check above). Say so in the log rather than fail a sent card.
            logger.warning("decisions/approve: Take the lead action %d done but not allowed", instance.id)
            return _refresh(instance.id)
        _audit_allowed(str(grant.get("label") or ""), instance.id, bool(changed))
    return _refresh(instance.id)


def _provably_principal(request: Request) -> bool:
    """Whether this request is tied to the principal (signed sign-ins or
    local login), as turning Take the lead on needs."""
    from openexecutive.api.routes.take_the_lead import _provably_theirs
    from openexecutive.people.store import find_principal_person

    try:
        principal = find_principal_person()
    except Exception:
        return False
    return principal is not None and _provably_theirs(request, principal)


def _audit_allowed(label: str, decision_id: int, edited: bool) -> None:
    from openexecutive.audit import log_event

    try:
        log_event(
            "take_the_lead_changed", f"Allowed from a card: {label}", actor="user",
            details={"allowed": label, "decision_id": decision_id, "with_example": edited},
        )
    except Exception:
        logger.warning("decisions: couldn't audit an allowance", exc_info=True)


async def _lead_declined(instance: DecisionInstance) -> None:
    from openexecutive.orchestrator import take_the_lead

    take_the_lead.resolved(instance.id, "declined")


# Take the lead: an action the gate held (orchestrator.take_the_lead), for
# the person whose authority covers it or the principal. What it would do
# quotes the Executive's context, so it is private to them.
_TAKE_THE_LEAD = DecisionClassSpec(
    name="take_the_lead_action",
    principal_only=False,
    principal_and_approver=True,
    alert_source=DECISION_ALERT_SOURCE,
    approve=_carry_out_lead,
    after_reject=_lead_declined,
)

async def _carry_out_actions(
    instance: DecisionInstance, body: ApproveBody, request: Request, resolver: int | None
) -> DecisionInstance:
    """Do an action card's actions, exactly as stored, on its person's tap
    (``delegation.action_cards``, which checks the caller and each action
    again first). ``edits.only`` picks which of them; ``edits.allow`` is
    Approve + allow, with Suggested actions in training."""
    from openexecutive.delegation.action_cards import ApproveRefused, approve

    try:
        await approve(
            instance, caller=api_caller.caller(request), resolver=resolver,
            only=(body.edits or {}).get("only"), allow=(body.edits or {}).get("allow") is True,
        )
    except ApproveRefused as refused:
        raise HTTPException(
            status_code=refused.status, detail={"code": refused.code, "message": refused.message},
        ) from None
    return _refresh(instance.id)


async def _actions_dismissed(instance: DecisionInstance) -> None:
    from openexecutive.delegation.action_cards import dismissed

    await dismissed(instance)


# A card of actions the Executive suggested on a turn about someone's mail
# (delegation.action_cards): theirs alone, like a reply card, and never an
# alert.
_DELEGATED_ACTIONS = DecisionClassSpec(
    name="delegation_actions",
    principal_only=False,
    approver_only=True,
    alert_source=None,
    approve=_carry_out_actions,
    after_reject=_actions_dismissed,
)

async def _answer_invite(
    instance: DecisionInstance, body: ApproveBody, request: Request, resolver: int | None
) -> DecisionInstance:
    """Accept or decline a meeting invite in its person's own calendar, on
    their tap (``delegation.invites``, which checks the caller and the card
    again first). ``edits.answer``: accept (the default) or decline."""
    from openexecutive.delegation.invites import AnswerRefused, answer

    edits = body.edits or {}
    try:
        await answer(
            instance, caller=api_caller.caller(request), resolver=resolver,
            answer=edits.get("answer", "accept"), allow=edits.get("allow") is True,
        )
    except AnswerRefused as refused:
        raise HTTPException(
            status_code=refused.status, detail={"code": refused.code, "message": refused.message},
        ) from None
    return _refresh(instance.id)


async def _invite_dismissed(instance: DecisionInstance) -> None:
    from openexecutive.delegation.invites import dismissed

    await dismissed(instance)


# A meeting invite from someone the person knows (delegation.invites): theirs
# alone, like a reply card, and never an alert. Dismiss answers nothing.
_DELEGATED_INVITE = DecisionClassSpec(
    name="delegation_invite",
    principal_only=False,
    approver_only=True,
    alert_source=None,
    approve=_answer_invite,
    after_reject=_invite_dismissed,
)

async def _carry_out_department_action(
    instance: DecisionInstance, body: ApproveBody, request: Request, resolver: int | None
) -> DecisionInstance:
    """A team member's send or edit their department held
    (orchestrator.department_gate): do that exact call, once (claimed first),
    as it stands, and record who approved it."""
    from openexecutive.audit import log_event
    from openexecutive.memory.decision_ledger import claim_for_execution, finish_execution
    from openexecutive.orchestrator import take_the_lead

    payload = _parse_payload(instance)
    if not claim_for_execution(instance.id, resolver_person_id=resolver):
        raise HTTPException(status_code=409, detail="Someone else resolved this decision first.")
    try:
        result = await take_the_lead.carry_out(payload, by_principal=_approver_is_principal(request))
    except Exception as exc:
        logger.exception("decisions/approve: department action %d failed", instance.id)
        finish_execution(instance.id, STATUS_FAILED, final_payload={**payload, "error": type(exc).__name__})
        _clear_decision_alert(instance.id, "dismissed")
        _audit_department_action(log_event, "department_action_failed", instance, payload, resolver)
        raise HTTPException(
            status_code=502,
            detail="Something went wrong, so it may not have gone through. Check before trying again.",
        ) from None
    failed = take_the_lead.result_failed(result)
    finish_execution(
        instance.id,
        STATUS_FAILED if failed else STATUS_APPROVED_UNCHANGED,
        final_payload={**payload, "result": result[:2000]},
    )
    _clear_decision_alert(instance.id, "dismissed" if failed else "ack")
    _audit_department_action(
        log_event, "department_action_failed" if failed else "department_action_done",
        instance, payload, resolver,
    )
    if failed:
        raise HTTPException(status_code=502, detail=f"It couldn't do that: {result[:300]}")
    return _refresh(instance.id)


def _audit_department_action(
    log_event: Any, event_type: str, instance: DecisionInstance, payload: dict[str, Any],
    resolver: int | None,
) -> None:
    verb = {
        "department_action_done": "Approved and done",
        "department_action_failed": "Approved, but it failed",
        "department_action_declined": "Declined",
    }[event_type]
    try:
        log_event(
            event_type,
            f"{verb}: {payload.get('summary') or payload.get('tool')}"[:240],
            actor=f"person:{resolver}" if resolver is not None else "user",
            details={
                "decision_id": instance.id,
                "tool": payload.get("tool"),
                "requested_by_person_id": payload.get("requested_by_person_id"),
                "department": payload.get("department"),
                "resolved_by_person_id": resolver,
            },
            department=str(payload.get("department") or "") or None,
            private=True,
        )
    except Exception:
        logger.warning("decisions: couldn't audit department action %d", instance.id, exc_info=True)


async def _department_action_declined(instance: DecisionInstance) -> None:
    from openexecutive.audit import log_event

    _audit_department_action(
        log_event, "department_action_declined", instance, _parse_payload(instance),
        instance.resolver_person_id,
    )


# A send or edit a team member asked for in chat that their department's
# authority held (orchestrator.department_gate), for the approver it went to
# or the principal. What it says quotes the conversation, so nobody else on
# the team sees it.
_DEPARTMENT_ACTION = DecisionClassSpec(
    name="department_action",
    principal_only=False,
    principal_and_approver=True,
    alert_source=DECISION_ALERT_SOURCE,
    approve=_carry_out_department_action,
    after_reject=_department_action_declined,
)

async def _carry_out_app_action(
    instance: DecisionInstance, body: ApproveBody, request: Request, resolver: int | None
) -> DecisionInstance:
    """Something the person asked for in chat that waits for their tap
    (``orchestrator.app_control``: a delete, a share, turning on something
    that acts as them): do it with this request, the tapper's own, through
    the route its button calls, which checks them again. Claimed first, so it
    runs once; a card older than a day is turned down instead."""
    from openexecutive.audit import log_event
    from openexecutive.memory.decision_ledger import claim_for_execution, finish_execution
    from openexecutive.orchestrator import app_control

    payload = _parse_payload(instance)
    if app_control.card_stale(instance.created_at):
        mark_resolved(instance.id, STATUS_REJECTED, resolver_person_id=resolver)
        raise HTTPException(
            status_code=409, detail="This was more than a day ago, so it wasn't done. Ask again in chat.",
        )
    if not claim_for_execution(instance.id, resolver_person_id=resolver):
        raise HTTPException(status_code=409, detail="Someone else resolved this decision first.")
    details = {"decision_id": instance.id, "action": payload.get("action"), "id": payload.get("id")}
    try:
        did = await app_control.carry_out(payload, request)
    except (app_control.Refused, HTTPException) as exc:
        reason = app_control.refusal_text(exc) if isinstance(exc, HTTPException) else str(exc)
        finish_execution(instance.id, STATUS_FAILED, final_payload={**payload, "error": reason})
        log_event("app_action_refused", f"Card {instance.id} refused", actor="user", details=details)
        status_code = exc.status_code if isinstance(exc, HTTPException) and exc.status_code < 500 else 409
        raise HTTPException(status_code=status_code, detail=reason) from None
    except Exception:
        logger.exception("decisions/approve: app action %d failed", instance.id)
        finish_execution(instance.id, STATUS_FAILED, final_payload={**payload, "error": "failed"})
        raise HTTPException(
            status_code=502, detail="That didn't go through. Check before trying again.",
        ) from None
    finish_execution(instance.id, STATUS_APPROVED_UNCHANGED, final_payload={**payload, "did": did})
    log_event("app_action_done", did[:200], actor="user", details=details)
    return _refresh(instance.id)


# Something asked for in chat that waits for its person's tap
# (orchestrator.app_control): theirs alone, and never an alert.
_APP_ACTION = DecisionClassSpec(
    name="app_action",
    principal_only=False,
    approver_only=True,
    alert_source=None,
    approve=_carry_out_app_action,
)

DECISION_CLASSES: dict[str, DecisionClassSpec] = {
    spec.name: spec
    for spec in (
        _MEETING_BOOKING, _DELEGATED_REPLY, _TAKE_THE_LEAD, _DELEGATED_ACTIONS, _DEPARTMENT_ACTION,
        _APP_ACTION, _DELEGATED_INVITE,
    )
}


@router.post("/decisions/{instance_id}/approve", response_model=DecisionInstance)
async def approve_decision(
    instance_id: int, body: ApproveBody, request: Request
) -> DecisionInstance:
    instance = _visible_instance(instance_id, request)
    spec = _spec_for(instance)
    resolver = _resolver(instance, request)
    if instance.status != STATUS_PROPOSED:
        raise HTTPException(
            status_code=409,
            detail=f"Cannot approve a decision with status={instance.status!r}",
        )
    return await spec.approve(instance, body, request, resolver)


@router.post("/decisions/{instance_id}/reject", response_model=DecisionInstance)
async def reject_decision(instance_id: int, body: RejectBody, request: Request) -> DecisionInstance:
    instance = _visible_instance(instance_id, request)
    spec = _spec_for(instance)
    resolver = _resolver(instance, request)
    return await _reject(instance, spec, resolver)


async def _reject(
    instance: DecisionInstance, spec: DecisionClassSpec, resolver: int | None
) -> DecisionInstance:
    instance_id = instance.id
    if instance.status != STATUS_PROPOSED:
        raise HTTPException(
            status_code=409,
            detail=f"Cannot reject a decision with status={instance.status!r}",
        )
    if not mark_resolved(instance_id, STATUS_REJECTED, resolver_person_id=resolver):
        raise HTTPException(status_code=409, detail="Someone else resolved this decision first.")
    _clear_decision_alert(instance_id, "dismissed", spec.alert_source)
    updated = _refresh(instance_id)
    if spec.after_reject is not None:
        try:
            await spec.after_reject(updated)
        except Exception:
            logger.exception("decisions/reject: after-reject step failed for instance %d", instance_id)
    return updated


# The cards a chat app shows with Approve and Skip buttons
# (integrations.channel_cards): the two a chat reply leaves for the person
# chatting, as the web chat shows them under its reply.
CHAT_CARD_CLASSES = frozenset({_CALENDAR_CLASS, "delegation_actions", "app_action"})
# Of the app_action cards (orchestrator.app_control), the ones a chat app's
# tap may carry out: those whose action checks the tapper itself, not a
# signed request (a workflow change, workflow_change.run).
CHAT_APP_ACTIONS = frozenset({"change_workflow"})


def shown_in_chat(instance: DecisionInstance) -> bool:
    """Whether a chat app shows this card with Approve and Skip buttons."""
    if instance.decision_class not in CHAT_CARD_CLASSES:
        return False
    if instance.decision_class != _APP_ACTION.name:
        return True
    return _parse_payload(instance).get("action") in CHAT_APP_ACTIONS


class _ChatTapRequest:
    """What an app_action card's action reads on a chat app's tap: the
    proven tap, and no signed caller (``workflow_change._tapper``)."""

    def __init__(self, tap: Any) -> None:
        self.state = SimpleNamespace(chat_tap=tap)
        self.headers: dict[str, str] = {}
        self.query_params: dict[str, str] = {}
        self.client = None


async def resolve_in_chat(instance_id: int, person: Any, *, approve: bool) -> DecisionInstance:
    """Approve or skip a card tapped in a chat app, for ``person``: the one the
    adapter proved tapped it. The rule is the web chat's (``_resolver``): a
    card of actions is its person's alone; a meeting is the principal's, or
    its approver's unless it is the principal's private booking. Raises
    HTTPException, as the routes do."""
    from openexecutive.delegation.action_cards import ApproveRefused
    from openexecutive.delegation.action_cards import approve as approve_actions
    from openexecutive.delegation.gmail import normalize_email
    from openexecutive.delegation.verified import ChatTap
    from openexecutive.people.store import find_principal_person

    instance = get_decision_instance(instance_id)
    if instance is None or not shown_in_chat(instance) or person.id is None:
        raise HTTPException(status_code=404, detail="This card is no longer there.")
    spec = _spec_for(instance)
    principal = find_principal_person()
    is_principal = principal is not None and principal.id == person.id
    if _approver_only(instance):
        allowed = person.id == instance.approver_person_id
    else:
        allowed = is_principal or (person.id == instance.approver_person_id and not _is_private(instance))
    if not allowed:
        # As the routes: a card that isn't theirs is not there.
        raise HTTPException(status_code=404, detail="This card is no longer there.")
    if not approve:
        return await _reject(instance, spec, person.id)
    if instance.status != STATUS_PROPOSED:
        raise HTTPException(status_code=409, detail="This card was already handled.")
    if instance.decision_class == _CALENDAR_CLASS:
        return await _book(instance, ApproveBody(), by_principal=is_principal, resolver=person.id)
    if instance.decision_class == _APP_ACTION.name:
        tap = ChatTap(normalize_email(person.email or ""))
        return await _carry_out_app_action(instance, ApproveBody(), _ChatTapRequest(tap), person.id)  # type: ignore[arg-type]
    try:
        await approve_actions(
            instance, caller=ChatTap(normalize_email(person.email or "")), resolver=person.id,
        )
    except ApproveRefused as refused:
        raise HTTPException(status_code=refused.status, detail=refused.message) from None
    return _refresh(instance.id)


@router.post("/decisions/{instance_id}/cancel", response_model=DecisionInstance)
async def cancel_decision(instance_id: int, request: Request) -> DecisionInstance:
    """Cancel an approved/executed event (reverse it)."""
    instance = _visible_instance(instance_id, request)
    spec = _spec_for(instance)
    _resolver(instance, request)
    if spec.cancel is None:
        raise HTTPException(status_code=409, detail="This decision can't be undone.")
    if instance.status not in (
        STATUS_APPROVED_UNCHANGED, STATUS_APPROVED_WITH_EDIT, STATUS_PROPOSED,
    ):
        raise HTTPException(
            status_code=409,
            detail=f"Cannot cancel a decision with status={instance.status!r}",
        )
    await spec.cancel(instance)
    mark_reversed(instance_id, reason="cancelled_via_ui", decision_class=spec.name)
    _clear_decision_alert(instance_id, "dismissed", spec.alert_source)
    return _refresh(instance_id)


def _class_mode_response(decision_class: str) -> DecisionClassMode:
    # An unknown stored value reads as the fail-safe default, like the gate.
    mode = get_class_mode(decision_class)
    return DecisionClassMode(
        decision_class=decision_class,
        mode="auto_execute" if mode == "auto_execute" else "propose",
    )


def _has_active_principal() -> bool:
    """Whether a non-archived principal is on the roster. Fails closed."""
    from openexecutive.people.store import find_principal_person

    try:
        return find_principal_person() is not None
    except Exception:
        logger.exception("decisions: principal lookup failed — treating as none")
        return False


@router.get(
    f"/decisions/classes/{_CALENDAR_CLASS}", response_model=DecisionClassMode
)
def get_meeting_class_mode() -> DecisionClassMode:
    """Whether the Executive proposes meetings for approval or books them."""
    return _class_mode_response(_CALENDAR_CLASS)


@router.put(
    f"/decisions/classes/{_CALENDAR_CLASS}", response_model=DecisionClassMode
)
def set_meeting_class_mode(
    request: Request, body: DecisionClassModeUpdate
) -> DecisionClassMode:
    """Set the meeting class mode. Principal only — the same rule as the
    workspace settings (``chat._caller_is_principal_or_unclaimed``): letting
    the Executive book meetings on its own is the principal's call. While no
    principal exists (when that rule lets anyone in) only ``propose`` can be
    set — ``auto_execute`` is a 409. Every change is audited."""
    from openexecutive.api.routes.chat import _caller_is_principal_or_unclaimed

    if not _caller_is_principal_or_unclaimed(request):
        raise HTTPException(
            status_code=403,
            detail="Only the principal can change how meetings are scheduled",
        )
    if body.mode == "auto_execute" and not _has_active_principal():
        # Before anyone is the principal the PUT is open to every caller (so
        # first-run setup is never locked out), and auto-booking would then
        # be switched on by nobody in particular. Propose stays allowed.
        raise HTTPException(
            status_code=409,
            detail=(
                "Meetings can only be booked automatically once someone is set "
                "as the principal (the owner) on the People page. Until then "
                "they are proposed for approval."
            ),
        )
    before = _class_mode_response(_CALENDAR_CLASS).mode
    if body.mode != before:
        set_class_mode(_CALENDAR_CLASS, body.mode)
        from openexecutive.audit import log_event as audit_log

        audit_log(
            "decision_class_mode_changed",
            f"Meeting scheduling mode changed: {before} → {body.mode}",
            actor=api_caller.actor(request),
            details={
                "decision_class": _CALENDAR_CLASS,
                "mode": {"from": before, "to": body.mode},
            },
        )
    return _class_mode_response(_CALENDAR_CLASS)


@router.get("/audit/reliability", response_model=ReliabilityCard)
def get_reliability(
    request: Request,
    decision_class: str = _CALENDAR_CLASS,
    days: int = 30,
) -> ReliabilityCard:
    """How a class's decisions went. The principal's alone: it counts every
    instance, private ones included."""
    if not _approver_is_principal(request):
        raise HTTPException(status_code=403, detail="Only the owner can see this.")
    if days < 1 or days > 365:
        raise HTTPException(status_code=400, detail="days must be 1–365")
    return aggregate_reliability(decision_class, window_days=days)