Skip to content

Self-improving AI Employees for everyone

23.1 KB
Raw Blame
"""EmployeeSummary: what Normal mode shows for one employee.

An employee is a workflow. Hired ones have an ``employees`` row with what
the hire screen captured; ones built in the editor are described from the
graph (``derived: true``). Either way the live parts come from the same
places the editor reads: the latest control generation (state and the
capabilities Start / Pause / Resume need) and the credential store (which
apps are connected). A browser that is waiting for the owner is live
plugin state (``node_signals``); the plugin re-sends the summary when it
changes.

A team list costs one query per table, never one per workflow, and never
calls Temporal: the list shows the last recorded control state, and the
single-workflow status handler stays the place that reconciles.

The server decides status and default task text; the client only overlays
live node activity on the task line and maps status to a pill.

Talking to the employee (``talk``: state and the agent that answers,
talk.py) reads the running generation's graph while one is live, since its
node ids are the ones that report status; otherwise the saved graph.
``pending_changes`` says the saved graph would run differently from the
live generation (a tool added in Talk, an edit in Dev mode), so a restart
("Apply") is waiting.

``activation_state`` says how a hire's own start went (``saved`` until it
is tried, then ``blocked``, ``running`` or ``failed``; activation.py), so a
new hire's page can tell a start still under way from one that will not
come without the owner. It is null for a workflow built in the editor.
"""

from __future__ import annotations

from datetime import datetime, timezone
from typing import Any, Dict, Iterable, List, Mapping, Optional
from zoneinfo import ZoneInfo

from core.logging import get_logger
from services.deployment.control import serialize_control
from services.deployment.restart import LIVE_STATES, pending_changes
from services.employees import runs, store
from services.employees.context import SETTINGS_USER_ID
from services.employees.apps import AppSpec, get_app
from services.employees.connections import Connections
from services.employees.graph_index import (
    CHAT_TRIGGER_TYPE,
    SCHEDULE_TRIGGER_TYPE,
    GraphIndex,
    index_graph,
)
from services.employees.policy import asks_first
from services.employees.talk import TalkState, talk_state

logger = get_logger(__name__)

#: Control states that mean "on duty": listening for work or doing it.
WORKING_STATES = frozenset({"starting", "running", "resuming"})
PAUSED_STATES = frozenset({"pausing", "paused"})

_WEEKDAYS = ("Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday")


def _photo_url(workflow_id: str, employee: Any) -> Optional[str]:
    """Where the employee's photo is served (the workspace file route),
    versioned so a new photo replaces the old one in every cache."""
    path = getattr(employee, "photo_path", None)
    if not path:
        return None
    from services.media.workspace import workspace_file_url

    url = workspace_file_url(workflow_id, path)
    return f"{url}?v={_millis(getattr(employee, 'updated_at', None))}" if url else None


def _millis(*moments: Optional[datetime]) -> int:
    latest = 0
    for moment in moments:
        if moment is None:
            continue
        if moment.tzinfo is None:
            moment = moment.replace(tzinfo=timezone.utc)
        latest = max(latest, int(moment.timestamp() * 1000))
    return latest


def _plural(count: int, one: str, many: str) -> str:
    return one if count == 1 else many


def schedule_text(trigger: Mapping[str, Any]) -> str:
    """"Every weekday at 09:00" for a hire's schedule trigger."""
    every = trigger.get("every")
    at = str(trigger.get("at") or "").strip()
    suffix = f" at {at}" if at else ""
    if every == "hour":
        return "Every hour"
    if every == "day":
        return f"Every day{suffix}"
    if every == "weekday":
        return f"Every weekday{suffix}"
    if every == "week":
        day = str(trigger.get("day") or "").strip().capitalize()
        return f"Every {day}{suffix}" if day else f"Every week{suffix}"
    if every == "month":
        day = str(trigger.get("day") or "").strip()
        if day == "L":
            return f"On the last day of every month{suffix}"
        return f"On day {day} of every month{suffix}" if day else f"Every month{suffix}"
    return "On a schedule"


def _trigger_text(employee: Any, graph: GraphIndex) -> str:
    trigger = getattr(employee, "trigger", None) or {}
    kind = trigger.get("kind") if isinstance(trigger, Mapping) else None
    if kind == "app_event":
        app = get_app(str(trigger.get("app") or ""))
        if app is not None:
            return app.phrase("when", f"When something arrives in {app.name}")
    if kind == "schedule":
        return schedule_text(trigger)
    if kind == "manual":
        return "When you message them"
    app = graph.primary_trigger_app()
    if app is not None:
        return app.phrase("when", f"When something arrives in {app.name}")
    types = graph.trigger_types
    if SCHEDULE_TRIGGER_TYPE in types:
        return "On a schedule"
    if CHAT_TRIGGER_TYPE in types:
        return "When you message them"
    if types:
        return "When the workflow is triggered"
    return "When you start them"


#: A running employee whose only work is what the owner sends them.
_WAITING_FOR_OWNER = "Waiting for your messages"


def _waiting_text(employee: Any, graph: GraphIndex) -> str:
    trigger = getattr(employee, "trigger", None) or {}
    kind = trigger.get("kind") if isinstance(trigger, Mapping) else None
    app = get_app(str(trigger.get("app") or "")) if kind == "app_event" else None
    app = app or graph.primary_trigger_app()
    if app is not None and app.phrase("waiting"):
        return app.phrase("waiting")
    if kind == "schedule":
        return f"Waiting for the next run ({schedule_text(trigger).lower()})"
    if SCHEDULE_TRIGGER_TYPE in graph.trigger_types:
        return "Waiting for the next scheduled run"
    if kind == "manual" or CHAT_TRIGGER_TYPE in graph.trigger_types:
        return _WAITING_FOR_OWNER
    return "Waiting for work"


def _status(control: Mapping[str, Any]) -> str:
    state = control.get("state")
    if state == "failed":
        return "attention"
    if state in PAUSED_STATES:
        return "attention" if control.get("pause_reason") else "paused"
    if state in WORKING_STATES:
        return "working"
    return "ready"


def _attention_text(control: Mapping[str, Any]) -> str:
    detail = control.get("pause_detail") or control.get("terminal_reason")
    if control.get("state") in PAUSED_STATES:
        return str(detail) if detail else "Paused after repeated errors. Resume when it's fixed."
    return "Stopped after a problem. Open it in Dev mode to see what happened."


#: Task text while the agent waits in ``request_user``, by its reason.
_BROWSER_REQUEST_TEXT = {
    "login": "Needs you to sign in to a site in the browser",
    "captcha": "Needs you to solve a CAPTCHA in the browser",
    "two_factor": "Needs a sign-in code from you in the browser",
    "confirm": "Needs you to check something in the browser",
}


def _browser_request(workflow_id: str, graph: GraphIndex) -> Optional[Dict[str, Any]]:
    """The first browser node waiting for the owner (the agent called
    ``request_user``), read live from the Browser plugin.

    Identity and reason only: summaries are broadcast to every connected
    socket, so the agent's message stays behind the authorized live view.
    """
    from services.employees.node_signals import node_state

    for node_id in graph.browser_ids:
        state = node_state("browser", workflow_id, node_id)
        if not state or state.get("state") != "awaiting_user":
            continue
        request = state.get("request") or {}
        since = request.get("since")
        return {
            "node_id": node_id,
            "reason": str(request.get("reason") or "other"),
            "since": datetime.fromtimestamp(since, timezone.utc).isoformat() if isinstance(since, (int, float)) else None,
        }
    return None


def _task(
    status: str,
    *,
    control: Mapping[str, Any],
    pending: int,
    missing: List[Dict[str, Any]],
    needs_ai: bool,
    employee: Any,
    graph: GraphIndex,
    browser_request: Optional[Mapping[str, Any]] = None,
    talk_on: bool = False,
) -> Optional[Dict[str, str]]:
    """The card's task line, or None when the page already says it: a
    running employee that only waits for the owner's messages, with the
    message box right under the card."""
    if browser_request is not None:
        return {"label": "Waiting", "text": _BROWSER_REQUEST_TEXT.get(browser_request["reason"], "Needs your help in the browser")}
    if pending > 0:
        return {"label": "Waiting", "text": f"{pending} {_plural(pending, 'draft is', 'drafts are')} waiting for you to check"}
    if status == "working":
        text = _waiting_text(employee, graph)
        return None if talk_on and text == _WAITING_FOR_OWNER else {"label": "Now", "text": text}
    if status == "attention":
        return {"label": "Paused", "text": _attention_text(control)}
    if status == "paused":
        return {"label": "Paused", "text": "Paused. Resume to pick up where they left off."}
    if missing:
        return {"label": "Next", "text": f"Connect {missing[0]['name']} to start"}
    if needs_ai:
        return {"label": "Next", "text": "Connect an AI model to start"}
    return {"label": "Next", "text": "Ready to start"}


def _derived_role(graph: GraphIndex) -> str:
    app = graph.primary_trigger_app()
    if graph.has_agent:
        if app is not None:
            return f"{app.name} assistant"
        if SCHEDULE_TRIGGER_TYPE in graph.trigger_types:
            return "Scheduled assistant"
        return "AI assistant"
    return "Workflow"


async def _apps(graph: GraphIndex, parameters: Mapping[str, Mapping[str, Any]], connections: Connections) -> List[AppSpec]:
    """The apps the graph's nodes use, hired or not: an app the hire named
    but the graph left out (a tool that sends while they ask first) is not
    one to connect, and one added later is. ``parameters`` are the saved
    parameters of the nodes whose app a parameter names (a custom
    connector's); one that is no longer saved is not listed."""
    apps = [await connections.app(app_id) for app_id in graph.apps_named(parameters)]
    return [app for app in apps if app is not None]


async def _node_parameters(database: Any, graphs: Iterable[GraphIndex]) -> Dict[str, Dict[str, Any]]:
    """The saved parameters of the nodes whose app a parameter names, for
    every graph in one query."""
    from sqlmodel import select

    from models.database import NodeParameter

    ids = [node_id for graph in graphs for node_id in graph.app_params]
    if not ids:
        return {}
    try:
        async with database.get_session() as session:
            rows = (await session.execute(select(NodeParameter).where(NodeParameter.node_id.in_(ids)))).scalars().all()
    except Exception:
        logger.warning("Could not read which apps employees' nodes name", exc_info=True)
        return {}
    return {row.node_id: dict(row.parameters or {}) for row in rows}


def _talk(graph: GraphIndex, control_row: Any) -> TalkState:
    """The live generation's talk line while one is live (the agent there
    is the one whose status the page follows), else the saved graph's."""
    if control_row is not None and control_row.status in LIVE_STATES:
        return talk_state(control_row.graph_snapshot or {})
    return graph.talk


async def _summary(
    workflow: Any,
    employee: Any,
    control_row: Any,
    *,
    graph: GraphIndex,
    parameters: Mapping[str, Mapping[str, Any]],
    connections: Connections,
    needs_ai: bool,
    pending: int,
    done_today: int,
    activation_state: Optional[str] = None,
) -> Dict[str, Any]:
    from services.workspace_capabilities import workspace_nodes

    control = serialize_control(control_row)
    control.setdefault("workflow_id", workflow.id)
    apps = [await connections.app_ref(app) for app in await _apps(graph, parameters, connections)]
    missing = [ref for ref in apps if not ref["connected"]]
    status = _status(control)
    roles = getattr(employee, "node_roles", None) or {}
    watch = [roles[key] for key in ("agent", "todos") if roles.get(key)] if roles else []
    if getattr(employee, "team_plan", None):
        watch = list(dict.fromkeys([*watch, *graph.agent_ids, *graph.todo_ids]))
    if not watch:
        watch = list(graph.agent_ids) + list(graph.todo_ids)
    talk = _talk(graph, control_row)
    # The board Home's Workspace shows: the one the hire made, while it is
    # still in the graph, else the first canvas the owner added.
    canvas = roles.get("canvas") if roles else None
    canvas_node_id = canvas if canvas in graph.canvas_ids else next(iter(graph.canvas_ids), None)
    browser_request = _browser_request(workflow.id, graph)
    return {
        "workflow_id": workflow.id,
        "name": workflow.name,
        #: The photo the owner gave them; null shows their initial.
        "photo_url": _photo_url(workflow.id, employee),
        "role": (getattr(employee, "role", "") or _derived_role(graph)),
        "color_role": getattr(employee, "color_role", None) or "agent",
        "derived": employee is None,
        "status": status,
        "task": _task(
            status,
            control=control,
            pending=pending,
            missing=missing,
            needs_ai=needs_ai,
            employee=employee,
            graph=graph,
            browser_request=browser_request,
            talk_on=talk.state == "on",
        ),
        "done_today": done_today,
        "pending_approvals": pending,
        "apps": apps,
        "missing_apps": missing,
        "unsupported_apps": list(getattr(employee, "unsupported_apps", None) or []),
        "needs_ai": needs_ai,
        "control": control,
        "watch_node_ids": watch,
        "canvas_node_id": canvas_node_id,
        "workspace_nodes": workspace_nodes(getattr(workflow, "data", None) or {}),
        "browser_nodes": [{"node_id": node_id, "label": graph.labels.get(node_id) or "Browser"} for node_id in graph.browser_ids],
        #: A browser node waiting for the owner ({node_id, reason, since}),
        #: else None. Read live, so it changes without a new revision.
        "browser_request": browser_request,
        #: {state: on | off | unsupported, agent_node_id}.
        "talk": talk.summary(),
        #: A hire's "ask me first" rule; built in the editor: whether its
        #: replies wait at an approval gate.
        "asks_first": asks_first(employee) if employee is not None else bool(graph.gate_ids),
        "pending_changes": pending_changes(workflow, control_row),
        "revision": _millis(
            getattr(workflow, "updated_at", None),
            getattr(employee, "updated_at", None),
            getattr(control_row, "updated_at", None),
        ),
        "hired_at": employee.hired_at.isoformat() if employee is not None and employee.hired_at else None,
        "activation_state": activation_state,
    }


async def _pending_counts(database: Any, workflow_ids: Iterable[str]) -> Dict[str, int]:
    """Drafts waiting for the owner, per workflow (the approval gate)."""
    from services.approvals.queries import pending_approvals_by_workflow

    try:
        return await pending_approvals_by_workflow(database, workflow_ids)
    except Exception:
        logger.warning("Could not count waiting drafts", exc_info=True)
        return {}


async def _activation_states(database: Any, workflow_ids: Iterable[str]) -> Dict[str, str]:
    """How each hire's own start went, per workflow (employee_activations)."""
    from sqlmodel import select

    from models.employees import EmployeeActivation

    ids = list(workflow_ids)
    if not ids:
        return {}
    try:
        async with database.get_session() as session:
            rows = (await session.execute(select(EmployeeActivation).where(EmployeeActivation.workflow_id.in_(ids)))).scalars().all()
    except Exception:
        logger.warning("Could not read how hires started", exc_info=True)
        return {}
    return {row.workflow_id: row.state for row in rows}


async def _owner_zone(database: Any) -> ZoneInfo:
    """The owner's time zone (Settings > Profile), UTC when unset or unreadable."""
    try:
        settings = await database.get_user_settings(SETTINGS_USER_ID) or {}
    except Exception:
        settings = {}
    return runs.owner_zone(settings.get("profile_timezone"))


async def _done_today(database: Any, workflow_ids: Iterable[str]) -> Dict[str, int]:
    """Successful runs since the start of the owner's day, per workflow."""
    zone = await _owner_zone(database)
    try:
        return await runs.done_today(database, workflow_ids, zone=zone)
    except Exception:
        logger.warning("Could not count today's runs", exc_info=True)
        return {}


async def employee_usage(database: Any, *, now: Optional[datetime] = None) -> Dict[str, Any]:
    """Settings > Billing: the team's successful runs so far this month, and
    ``since``, the day the count starts (the 1st in the owner's zone, as
    YYYY-MM-DD), so the page says the period in the owner's own terms.

    Errors propagate, so the page shows that the count is unavailable
    rather than a zero.
    """
    zone = await _owner_zone(database)
    now = now or datetime.now(timezone.utc)
    return {
        "tasks_this_month": await runs.done_this_month(database, zone=zone, now=now),
        "since": runs.start_of_month(now, zone).astimezone(zone).date().isoformat(),
    }


async def _latest_run(database: Any, workflow_id: str) -> Optional[Dict[str, Any]]:
    """The most recent finished run."""
    try:
        return await runs.latest_run(database, workflow_id)
    except Exception:
        logger.warning("Could not read the latest run", workflow_id=workflow_id, exc_info=True)
        return None


def employee_owner(workflow: Any, employee: Any = None) -> str:
    """Explicit graph ownership wins; old hires retain their recorded owner."""
    from constants import OWNER_PRINCIPAL_ID

    return str((getattr(workflow, "data", None) or {}).get("owner_id") or getattr(employee, "owner_id", None) or OWNER_PRINCIPAL_ID)


async def list_employee_summaries(database: Any, *, auth_service: Any, owner_id: Optional[str] = None) -> List[Dict[str, Any]]:
    """Workflows as employees, optionally restricted to their trusted owner."""
    workflows = await database.get_all_workflows()
    ids = [workflow.id for workflow in workflows]
    employees = await store.list_by_workflow_ids(database, ids)
    if owner_id is not None:
        workflows = [workflow for workflow in workflows if employee_owner(workflow, employees.get(workflow.id)) == owner_id]
        ids = [workflow.id for workflow in workflows]
    controls = await database.list_latest_workflow_controls(ids)
    pending = await _pending_counts(database, ids)
    done = await _done_today(database, ids)
    activations = await _activation_states(database, ids)
    graphs = {workflow.id: index_graph(getattr(workflow, "data", None)) for workflow in workflows}
    parameters = await _node_parameters(database, graphs.values())
    connections_by_owner = {}
    summaries = []
    for workflow in workflows:
        principal = employee_owner(workflow, employees.get(workflow.id))
        if principal not in connections_by_owner:
            connection = Connections(auth_service, principal=principal)
            connections_by_owner[principal] = (connection, not await connection.has_ai())
        connections, needs_ai = connections_by_owner[principal]
        summaries.append(await _summary(
            workflow,
            employees.get(workflow.id),
            controls.get(workflow.id),
            graph=graphs[workflow.id],
            parameters=parameters,
            connections=connections,
            needs_ai=needs_ai,
            pending=pending.get(workflow.id, 0),
            done_today=done.get(workflow.id, 0),
            activation_state=activations.get(workflow.id),
        ))
    return summaries


async def _load_one(database: Any, workflow_id: str, *, auth_service: Any) -> Optional[tuple]:
    workflow = await database.get_workflow(workflow_id)
    if workflow is None:
        return None
    employee = await store.get_by_workflow(database, workflow_id)
    control = await database.get_latest_workflow_control(workflow_id)
    pending = await _pending_counts(database, [workflow_id])
    done = await _done_today(database, [workflow_id])
    activations = await _activation_states(database, [workflow_id])
    connections = Connections(auth_service, principal=employee_owner(workflow, employee))
    graph = index_graph(getattr(workflow, "data", None))
    summary = await _summary(
        workflow,
        employee,
        control,
        graph=graph,
        parameters=await _node_parameters(database, [graph]),
        connections=connections,
        needs_ai=not await connections.has_ai(),
        pending=pending.get(workflow_id, 0),
        done_today=done.get(workflow_id, 0),
        activation_state=activations.get(workflow_id),
    )
    if employee and employee.team_plan:
        from services.employees.jobs import job_progress
        summary["job_progress"] = await job_progress(database, workflow_id)
    from services.employees.work_progress import work_progress
    summary["work_progress"] = await work_progress(
        database, workflow, control=control,
        pending_approvals=summary["pending_approvals"], browser_request=summary["browser_request"],
        job_status=summary.get("job_progress"),
    )
    summary["has_team"] = bool(employee and employee.team_plan)
    from core.container import container
    summary["can_give_team"] = bool(employee and not employee.team_plan and getattr(container.settings(), "employee_team_conversion_enabled", False)) if hasattr(container, "settings") else False
    return summary, workflow, employee


async def get_employee_summary(database: Any, workflow_id: str, *, auth_service: Any) -> Optional[Dict[str, Any]]:
    loaded = await _load_one(database, workflow_id, auth_service=auth_service)
    return loaded[0] if loaded else None


async def get_employee_detail(database: Any, workflow_id: str, *, auth_service: Any) -> Optional[Dict[str, Any]]:
    """The summary plus what the employee card and its setup screen show."""
    loaded = await _load_one(database, workflow_id, auth_service=auth_service)
    if loaded is None:
        return None
    summary, workflow, employee = loaded
    last_run = await _latest_run(database, workflow_id)
    return {
        **summary,
        "description": getattr(employee, "description", "") or "",
        "job": getattr(employee, "job", "") or "",
        "plan": list(getattr(employee, "plan", None) or []),
        "rules": dict(getattr(employee, "rules", None) or {}),
        "choices": list(getattr(employee, "choices", None) or []),
        "trigger_text": _trigger_text(employee, index_graph(getattr(workflow, "data", None))),
        "latest_report": (last_run or {}).get("report"),
        "last_run": last_run,
    }


__all__ = [
    "employee_usage",
    "get_employee_detail",
    "get_employee_summary",
    "list_employee_summaries",
    "schedule_text",
]