Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""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",
]