AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""Chat's tools in workflow action steps: one list, chat's own handlers.
Every tool the chat can offer is labelled here, once (``ACCESS``), and a unit
test fails when a chat tool has no label, so a tool added to the chat is
always decided for workflows too:
- ``USE``: a step may name it as ``oe__<name>`` and it runs through the chat's
own handler (``tool_catalog`` lists these with the other built-ins).
- ``AS_ME``: reads or writes the person's own mailbox or calendar (Act as
me). Not offered to workflows yet: it needs its own identity rules.
- ``COVERED``: workflows do this their own way (a specialist step, naming a
gateway tool directly, the step's own ``run_script``).
- ``CHAT_ONLY``: it needs the person: they are on screen, or it changes what
the Executive believes or who is on the team, which chat keeps to a turn
the person is in (most are ``schedule_tools.UNATTENDED_WITHHELD_TOOLS``). A
workflow reads outside text (mail, pages), and a line in it must not
quietly rewrite memory with nobody watching. Goal progress and the
watchlist are the exception, by the owner's choice: keeping them current
is what a scheduled workflow is for, the step has to be given the tool by
name when the workflow is saved, and each change is audited.
**How a chat tool runs in a step.** The step's call goes through the usual
checks first (the allowlist, the budget, the first-write target hold in
``action_step``). Then the chat handler runs on a session of its own, as the
chat's unattended runs do (``Session.unattended``: the scheduler's proactive
run, the reflection): the handlers already know that nobody is in the
conversation and refuse what needs someone there. The session's documents
are those of the person the run is for (``artifact_records.current_viewer``),
and a tool the workspace mode doesn't offer is refused
(``filter_tools_for_workspace_mode``). Take the lead does not gate these
calls: a saved workflow is its creator's own instruction, approved tool by
tool when they saved it, as for the gateway tools. A workflow a team member
created goes through their department's approval level, as their own chat
turn would (``department_gate``). One with no creator on record (saved
before creators were) runs as the principal's, as its tools always did.
**Long and nested runs.** ``run_workflow`` and ``run_executive_research``
get a longer timeout than other calls (``TIMEOUT_S``), and a workflow may not
start itself or one already running above it, nor go more than
``MAX_DEPTH`` workflows deep.
**Web search** is the model's own server tool, not a handler: a step that
names ``oe__web_search`` has it added to the model's tools
(``action_step.run_action_step``).
"""
from __future__ import annotations
import contextlib
import contextvars
import dataclasses
import json
import logging
from collections.abc import Awaitable, Callable, Iterator
from typing import Any
logger = logging.getLogger(__name__)
PREFIX = "oe__"
USE = "use"
AS_ME = "as_me"
COVERED = "covered"
CHAT_ONLY = "chat_only"
WEB_SEARCH = "web_search"
# Every tool the chat can offer: (label, why). Grouped by label.
ACCESS: dict[str, tuple[str, str]] = {
# USE: runs in a step through the chat's own handler.
"search_skills": (USE, "find a playbook"),
"load_skill": (USE, "read a playbook"),
"search_knowledge": (USE, "search the company knowledge base"),
"read_document": (USE, "read an uploaded document"),
WEB_SEARCH: (USE, "search the web (the model's server tool)"),
"run_executive_research": (USE, "run the research council"),
"list_workflows": (USE, "list workflows"),
"run_workflow": (USE, "run another workflow"),
"run_python_job": (CHAT_ONLY, "reads the principal's Knowledge files; unattended runs never get it"),
"draft_artifact": (USE, "publish a document, sheet or report"),
"get_artifact": (USE, "read a past deliverable"),
"list_artifacts": (USE, "list past deliverables"),
"create_alert": (USE, "raise an alert"),
"find_alerts": (USE, "look up alerts"),
"message_person": (USE, "message someone on the roster"),
"send_slack_dm": (USE, "Slack direct message"),
"send_discord_dm": (USE, "Discord direct message"),
"send_telegram_message": (USE, "Telegram message"),
"send_department_message": (USE, "post to a department room"),
"send_company_broadcast": (USE, "post company-wide"),
"schedule_followup": (USE, "queue a follow-up message"),
"suggest_workflow": (USE, "suggest a workflow to run"),
"list_followups": (USE, "list pending follow-ups"),
"create_calendar_event": (USE, "book a meeting through the meeting gate"),
"create_instant_meeting": (USE, "start a meeting now"),
"cancel_calendar_event": (USE, "cancel a meeting it booked"),
"list_people": (USE, "read the roster"),
"lookup_person": (USE, "find someone on the roster"),
"ask_about_person": (USE, "ask what is known about someone"),
"list_open_loops": (USE, "list open loops"),
"list_department_goals": (USE, "list goals"),
"list_watchlist": (USE, "list the watchlist"),
"add_watchlist_entry": (USE, "watch something new"),
"tune_watchlist_entry": (USE, "tune what is watched"),
"remove_watchlist_entry": (USE, "stop watching something"),
"update_department_goal": (USE, "update a goal's progress"),
# AS_ME: the person's own mailbox and calendar.
"ghostwrite_email": (AS_ME, "write an email as the person"),
"search_my_email": (AS_ME, "search the person's own mailbox"),
"read_my_email": (AS_ME, "read the person's own mail"),
"read_my_email_attachment": (AS_ME, "read an attachment in the person's mail"),
"save_my_email_attachment": (AS_ME, "save an attachment from the person's mail"),
"my_email_awaiting_reply": (AS_ME, "the person's unanswered sent mail"),
"my_email_read_before": (AS_ME, "mail opened for the person before"),
"my_calendar": (AS_ME, "the person's own calendar"),
"remind_me": (AS_ME, "a reminder for the person"),
"propose_actions": (AS_ME, "an approval card from the person's mail"),
"recall_history": (AS_ME, "the person's own conversation notes"),
# COVERED: workflows have their own way.
"consult_specialist": (COVERED, "a specialist step"),
"search_tools": (COVERED, "a step names gateway tools directly"),
"call_tool": (COVERED, "a step names gateway tools directly"),
"load_mcp_server": (COVERED, "connections are set up outside a run"),
"run_script": (COVERED, "every action step has run_script"),
"list_saved_tools": (COVERED, "every action step's script lists them"),
"open_tools": (COVERED, "a step names its tools up front"),
"use_tool": (COVERED, "a step names its tools up front"),
# CHAT_ONLY: needs the person (module docstring).
"remember_fact": (CHAT_ONLY, "changes what the Executive takes as fact"),
"forget_fact": (CHAT_ONLY, "changes what the Executive takes as fact"),
"update_company_profile": (CHAT_ONLY, "changes the company profile"),
"create_goal": (CHAT_ONLY, "only the principal starts a goal"),
"record_decision_outcome": (CHAT_ONLY, "only the principal records an outcome"),
"assign_open_loop": (CHAT_ONLY, "takes the task in the speaker's own words"),
"close_open_loop": (CHAT_ONLY, "only the principal or the loop's owner closes it"),
"ack_alert": (CHAT_ONLY, "clears an alert on quoted text"),
"leave_out_of_brief": (CHAT_ONLY, "a correction the person asks for"),
"cancel_followup": (CHAT_ONLY, "a correction the person asks for"),
"move_followup": (CHAT_ONLY, "a correction the person asks for"),
"upsert_person": (CHAT_ONLY, "changes the roster"),
"archive_person": (CHAT_ONLY, "changes the roster"),
"set_department_head": (CHAT_ONLY, "changes the roster"),
"resolve_roster_request": (CHAT_ONLY, "answers a roster request"),
"do_in_app": (CHAT_ONLY, "acts in the app as the person"),
"find_in_app": (CHAT_ONLY, "acts in the app as the person"),
"propose_form_values": (CHAT_ONLY, "fills a form on the person's screen"),
"open_in_app": (CHAT_ONLY, "a link for the person on screen"),
"read_user_guide": (CHAT_ONLY, "explains the app to the person"),
"mark_draft_sent": (CHAT_ONLY, "the person says they sent it"),
"draft_workflow": (CHAT_ONLY, "a workflow does not build workflows"),
"save_workflow": (CHAT_ONLY, "a workflow does not build workflows"),
}
# Calls that run a whole job: longer than action_step's default timeout.
# Workflow tool names saved workflows may still list, and the chat tool each
# now runs. Not offered for new steps.
LEGACY_NAMES: dict[str, str] = {"oe__read_file": "read_document"}
TIMEOUT_S: dict[str, float] = {"run_workflow": 900.0, "run_executive_research": 900.0}
MAX_DEPTH = 3
def chat_tool_definitions() -> dict[str, dict[str, Any]]:
"""Every tool the chat can offer, by name (definitions as chat offers
them; web search is the model's server tool and has none here)."""
from openexecutive.orchestrator import tool_groups
from openexecutive.orchestrator.delegation_tools import DELEGATION_TOOLS
from openexecutive.orchestrator.executive import _offered_skill_tools
from openexecutive.orchestrator.history_tools import HISTORY_TOOLS
from openexecutive.orchestrator.knowledge_tools import KNOWLEDGE_TOOLS
from openexecutive.orchestrator.mcp_gateway import MCP_TOOLS
from openexecutive.orchestrator.router import SPECIALIST_TOOLS
from openexecutive.workflows import step_script
tools = [
*SPECIALIST_TOOLS, *_offered_skill_tools(), *MCP_TOOLS, *DELEGATION_TOOLS,
*HISTORY_TOOLS, *KNOWLEDGE_TOOLS, tool_groups.USE_TOOL_TOOL,
{"name": tool_groups.OPEN_TOOLS},
{"name": step_script.RUN_SCRIPT_TOOL}, {"name": step_script.LIST_SAVED_TOOLS_TOOL},
]
return {str(t["name"]): t for t in tools}
def _chat_handlers() -> dict[str, Callable[[dict[str, Any]], Awaitable[str]]]:
from openexecutive.orchestrator.executive import _ALL_SKILL_HANDLERS
from openexecutive.orchestrator.knowledge_tools import KNOWLEDGE_TOOL_HANDLERS
return {**_ALL_SKILL_HANDLERS, **KNOWLEDGE_TOOL_HANDLERS}
def label(name: str) -> str | None:
entry = ACCESS.get(name)
return entry[0] if entry else None
def workflow_name_for(chat_name: str) -> str:
return f"{PREFIX}{chat_name}"
# The workflows running in this task, outermost first, and the creator of
# the innermost one (set by ``action_step._dispatch``).
_chain: contextvars.ContextVar[tuple[str, ...]] = contextvars.ContextVar("workflow_chain", default=())
_creator: contextvars.ContextVar[int | None] = contextvars.ContextVar("workflow_tool_creator", default=None)
# Whether the outermost of them was started by one of the Executive's own
# unattended passes (the reflection, research, a proactive run): their
# context is stored or inbound text with nobody watching.
_by_a_pass: contextvars.ContextVar[bool] = contextvars.ContextVar("workflow_started_by_a_pass", default=False)
@contextlib.contextmanager
def in_workflow(workflow_name: str, creator_id: int | None) -> Iterator[None]:
"""Run the block as a step of ``workflow_name``, created by ``creator_id``."""
from openexecutive.orchestrator.schedule_tools import current_session
outermost = not _chain.get()
by_a_pass = _by_a_pass.set(
bool(getattr(current_session.get(), "unattended", False)) if outermost else _by_a_pass.get()
)
chain = _chain.set((*_chain.get(), workflow_name))
creator = _creator.set(creator_id)
try:
yield
finally:
_creator.reset(creator)
_chain.reset(chain)
_by_a_pass.reset(by_a_pass)
def running() -> tuple[tuple[str, ...], int | None]:
"""The workflows running in this task, outermost first, and the creator
of the innermost one (``in_workflow``)."""
return _chain.get(), _creator.get()
def started_by_a_pass() -> bool:
"""Whether the outermost running workflow was started by one of the
Executive's unattended passes rather than a person or its schedule."""
return _by_a_pass.get()
def _error(message: str) -> str:
return json.dumps({"error": message})
def _nested_run_refusal(tool_input: dict[str, Any]) -> str | None:
chain = _chain.get()
target = str(tool_input.get("name") or tool_input.get("workflow") or "").strip()
if target and target in chain:
return _error(f"{target!r} is already running in this chain of workflows, so it can't start again. Do not retry.")
if len(chain) >= MAX_DEPTH:
return _error(f"Workflows can start other workflows at most {MAX_DEPTH} deep. Do not retry.")
return None
def _seen_channel_refs() -> set[tuple[str, str]]:
"""The roster's own channels, as the reflection seeds them, so
``schedule_followup`` reaches only a real person's channel."""
from openexecutive.people.store import list_people
seen: set[tuple[str, str]] = set()
for person in list_people():
if person.slack_user_id:
seen.add(("slack_dm", person.slack_user_id))
if person.discord_user_id:
seen.add(("discord_dm", person.discord_user_id))
if person.telegram_chat_id:
seen.add(("telegram", person.telegram_chat_id))
if person.email:
seen.add(("email", person.email))
return seen
def _session(mode: str) -> Any:
from openexecutive.memory.workspace_settings import effective_principal_role
from openexecutive.onboarding.profile_builder import load_or_create_profile
from openexecutive.orchestrator.artifact_records import current_viewer
from openexecutive.orchestrator.session import Session
profile = load_or_create_profile()
return Session(
company_profile=profile if not profile.is_empty() else None,
seen_channel_refs=_seen_channel_refs(),
turn_workspace_mode=mode,
turn_principal_role=effective_principal_role(None),
unattended=True,
documents_viewer=current_viewer(),
)
def _team_member(person_id: int | None) -> Any:
"""The creator when they are a team member other than the principal."""
from openexecutive.people.store import get_person
if person_id is None:
return None
person = get_person(person_id)
if person is None or person.is_principal or person.kind != "team":
return None
return person
async def run_chat_tool(name: str, tool_input: dict[str, Any]) -> str:
"""Run the chat tool ``name`` for a workflow step (module docstring)."""
from openexecutive.memory.workspace_settings import effective_workspace_mode
from openexecutive.orchestrator import department_gate
from openexecutive.orchestrator.schedule_tools import (
current_session,
filter_tools_for_workspace_mode,
withheld_tool_error,
)
if label(name) != USE:
return _error(f"{name} is not available in workflows. Do not retry.")
handler = _chat_handlers().get(name)
if handler is None:
return _error(f"{name} is not available in workflows. Do not retry.")
if name == "run_workflow":
refused = _nested_run_refusal(tool_input)
if refused is not None:
return refused
mode = str(effective_workspace_mode(None))
if not filter_tools_for_workspace_mode([{"name": name}], mode):
return withheld_tool_error(name, mode)
session = _session(mode)
handlers: dict[str, Any] = {name: handler}
seat = _team_member(_creator.get())
if seat is not None:
handlers = department_gate.gated_handlers(handlers, seat, session_id=session.session_id)
token = current_session.set(session)
try:
return str(await handlers[name](tool_input))
finally:
current_session.reset(token)
def _usable_definitions() -> list[dict[str, Any]]:
definitions = chat_tool_definitions()
return [definitions[n] for n, (lbl, _) in ACCESS.items() if lbl == USE and n in definitions]
def not_offered() -> set[str]:
"""Workflow tool names that resolve but aren't shown for new steps: the
old names, and channel tools this instance has no token for (a call
would only error)."""
from openexecutive.config import get_settings
from openexecutive.orchestrator.schedule_tools import filter_tools_for_configured_channels
usable = _usable_definitions()
try:
kept = {t["name"] for t in filter_tools_for_configured_channels(usable, get_settings())}
except Exception:
logger.warning("workflow chat tools: couldn't read the configured channels", exc_info=True)
kept = {t["name"] for t in usable}
dropped = {workflow_name_for(str(t["name"])) for t in usable if t["name"] not in kept}
return set(LEGACY_NAMES) | dropped
def workflow_specs() -> dict[str, tuple[Any, Callable[[dict[str, Any]], Awaitable[str]]]]:
"""``{oe__name: (ToolInfo, handler)}`` for every ``USE`` chat tool, plus
the old names in ``LEGACY_NAMES``. All of them resolve, so a saved
workflow keeps validating; ``not_offered`` says which to leave out of
what new steps are shown."""
from openexecutive.workflows.tool_catalog import ToolInfo, read_only_label
usable = _usable_definitions()
specs: dict[str, tuple[Any, Callable[[dict[str, Any]], Awaitable[str]]]] = {}
for tool in usable:
chat_name = str(tool["name"])
schema = dict(tool.get("input_schema") or {"type": "object", "properties": {}})
async def run(tool_input: dict[str, Any], _name: str = chat_name) -> str:
return await run_chat_tool(_name, tool_input)
specs[workflow_name_for(chat_name)] = (
ToolInfo(
name=workflow_name_for(chat_name),
description=str(tool.get("description") or ""),
input_schema=schema,
read_only=read_only_label(chat_name, schema),
source="builtin",
timeout_s=TIMEOUT_S.get(chat_name),
),
run,
)
for legacy, chat_name in LEGACY_NAMES.items():
if workflow_name_for(chat_name) in specs:
info, handler = specs[workflow_name_for(chat_name)]
specs[legacy] = (dataclasses.replace(info, name=legacy), handler)
from openexecutive.orchestrator.web_search_tool import build_web_search_tool
if build_web_search_tool() is not None:
specs[workflow_name_for(WEB_SEARCH)] = (
ToolInfo(
name=workflow_name_for(WEB_SEARCH),
description=(
"Search the web for current facts, news, prices and sources. The "
"model searches as it writes; there is nothing to call."
),
input_schema={"type": "object", "properties": {}},
read_only=None,
source="server",
),
_web_search_not_callable,
)
return specs
async def _web_search_not_callable(tool_input: dict[str, Any]) -> str:
return _error("Web search runs as the model writes; it can't be called from a script.")