AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
from __future__ import annotations
import uuid
from dataclasses import dataclass, field
from datetime import datetime
from typing import TYPE_CHECKING, Any
from openexecutive.memory.company_profile import CompanyProfile
from openexecutive.memory.conversation_ids import is_rolling
if TYPE_CHECKING:
from openexecutive.memory.workspace_settings import PrincipalRole
def history_window_start(total: int, max_turns: int = 20, step_turns: int = 10) -> int:
"""Index of the first of ``total`` history messages the model is shown
(``Session.get_recent_history``): the last ``max_turns`` turns, the start
moving in steps of ``step_turns``. Messages before it are out of view."""
keep = max_turns * 2
if total <= keep:
return 0
step = max(1, step_turns) * 2
return ((total - keep) // step) * step
# The user turn put before history that opens with the Executive's message.
CONTINUED_PLACEHOLDER = "(Continuing our chat.)"
@dataclass
class Session:
session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
company_profile: CompanyProfile | None = None
conversation_history: list[dict[str, Any]] = field(default_factory=list)
created_at: datetime = field(default_factory=datetime.utcnow)
# (channel, channel_ref) pairs the Executive has seen during this session.
# Used by schedule_followup to refuse scheduling sends to refs the user
# never actually used — anti-spam guard.
seen_channel_refs: set[tuple[str, str]] = field(default_factory=set)
# Mailbox message and thread ids this conversation was shown by a search
# that left other teammates' mail out (or the inbound email it answers).
# The model may reach the Executive's mailbox only by these
# (orchestrator.teammate_mail).
mail_ids_seen: set[str] = field(default_factory=set)
# Who this conversation's mail actually reached: the lowercased to/cc
# addresses of every send the mailbox accepted, and the message ids an
# Outlook reply answered. The email poller reads them after an inbound
# email's turn to tell whether its sender got a reply
# (integrations.unanswered_mail).
mail_sent_to: set[str] = field(default_factory=set)
mail_replied_ids: set[str] = field(default_factory=set)
# Which inbound channel this session arrived on ("slack", "discord",
# "telegram", "google_chat", "email"), and the address on it. Empty for
# web/CLI turns and runs nobody started from a channel. Used when a
# workflow raises an approval gate mid-conversation: the gate records
# where to look for the answer, so a reply on this channel can resolve it
# (not on email, whose reply is no chat message — see `gate_delivery`).
# Also how `content_trust.principal_speaking` tells an inbound email from
# the principal's own surfaces: an email turn that left it empty was read
# as the web app's. Inbound vocabulary — see `normalize_channel`.
origin_channel: str = ""
origin_channel_ref: str = ""
# True only for a session minted by the web chat route. `origin_channel`
# cannot stand in for this: alert review, the CLI, the MCP server, the
# scheduler and the unattended workflows all leave it empty while being
# nothing like a browser turn. Anything that wants to treat browser turns
# differently has to ask for them by name.
from_web_chat: bool = False
# True only for a session minted by the CLI (`openexecutive ask` / `chat`),
# which runs on the host itself — the principal's own surface for
# `content_trust.principal_speaking`, as the web chat is.
from_cli: bool = False
# True only for a session minted by Open Executive's own MCP server
# (`mcp_server.ask_executive`): another AI app is asking, on behalf of
# `caller_person_id`. Such a turn reads and advises but never sends,
# posts, books, schedules, runs or changes anything: the chat loop
# neither offers nor runs `schedule_tools.MCP_CLIENT_WITHHELD_TOOLS`, Act
# as me, recall_history or extension tools, and of the gateway tools only
# the reads in `schedule_tools.MCP_CLIENT_MCP_TOOLS`. Never the
# principal's own surface for `content_trust.principal_speaking`.
from_mcp_client: bool = False
# Set with `from_mcp_client` when the request turned on "may act"
# (`mcp_server.ask_executive`: the `x-mcp-client-actions: on` header on a
# request the deployment's shared secret authenticated, or
# `MCP_CLIENT_ACTIONS` where no secret is configured). Such a turn runs
# the speaker's own changes inside Open Executive (alerts, open loops,
# follow-ups, the watch list, goals, decision outcomes, remembered facts,
# and company profile writes, never the roster, each under its own owner-only and
# person checks), counts as a verified surface for `caller_person_id`,
# and offers anything that reaches another person only as an approval
# card (`propose_actions`), which goes on its own only by the speaker's
# Handle it for me (`action_cards.on_its_own_refusal`). It is still
# never offered `schedule_tools.MCP_CLIENT_ACTING_WITHHELD_TOOLS`, Act as
# me's mailbox tools, recall_history or extension tools.
mcp_client_may_act: bool = False
# Set per turn by the web chat route when a host origin's page sent it
# (`api.caller.from_host`: another app that frames Open Executive and may
# call a short list of its routes, OE_HOST_ORIGINS, docs/auth.md), or
# wrote any earlier line of this conversation
# (`session_store.host_wrote`): that line stays in what the model reads.
# Its scripts aren't Open Executive's, so such a turn only reads and advises,
# as a read-only turn from another AI app does
# (`schedule_tools.read_only_turn`): nothing that sends, posts, books,
# schedules, runs or changes stored state, no Act as me, recall_history,
# script or extension tool, and of the gateway tools only the reads. What
# would act, the person does in Open Executive's own pages.
from_host: bool = False
# The rostered Person behind this conversation, when one is resolved. The
# adapters already pass this to `Executive.chat(person_id=...)`; holding it
# on the session too lets tool handlers running mid-turn tell "the approver
# is the person I'm already talking to" from "the approver is someone else".
caller_person_id: int | None = None
# Set by a channel adapter that verified for itself that `caller_person_id`
# is who sent this turn's message, on a channel the checks in
# `people_tools` don't know. That channel then counts as a verified
# surface (`people_tools._is_verified_speaker_surface`) for every gate
# that asks, as Slack and Discord do: an adapter sets it only when it
# resolved `caller_person_id` from a sender identity the platform
# authenticated, never from anything the message says, and per turn.
speaker_verified: bool = False
# The sender's People entry on a channel that names its sender but isn't
# one `people_tools` verifies (Google Chat, by the Google account email on
# its signed event). Read only by the department gate
# (`department_gate.speaker`), so the principal there isn't held and a
# teammate gets their own department's authority. Never a grant for
# anything else, and never set alongside `caller_person_id`.
gate_sender_person_id: int | None = None
# Set by a channel adapter when nobody but the speaker (and the
# Executive) can read the conversation, e.g. a direct message
# (`delegation.settings.private_conversation`, which also needs
# `speaker_verified`). Act as me and recalled notes also need the
# speaker's turn to be verified.
private_chat: bool = False
# The live alert board as the server derived it this turn, recorded by
# `briefing.context.render_and_trust`. `ack_alert` refuses anything else on
# EVERY session, web included, so an id quoted inside an alert's own body —
# alerts are minted from inbound mail and chat, so that text is
# attacker-controlled — cannot clear a row that is closed, snoozed or
# invented. It does not stop the model being argued into acking the wrong
# LIVE card; see `format_open_alerts_for_prompt` for the limits of this
# control. Empty means the turn was shown no board and can ack nothing.
# `find_alerts` is the one thing that adds to it after that, and only on a
# turn with `principal_board_shown` — so an open row off the board (read,
# snoozed, past TTL but not yet swept) can be cleared there too.
trusted_alert_ids: set[int] = field(default_factory=set)
# Whether `render_and_trust` showed THIS turn the principal's own board:
# the principal on a verified surface, and on a channel only in their DM
# (`channel_context.attach_briefing_context`). `find_alerts` answers and
# widens nothing without it — "principal on a verified surface" alone
# also passes the principal's turn in a shared Slack or Discord thread.
principal_board_shown: bool = False
# Ids `find_alerts` added to `trusted_alert_ids` this turn, capped across
# calls (`schedule_tools._FIND_ALERTS_MAX_PER_TURN`). Reset per turn with
# the trusted set.
found_alert_ids: set[int] = field(default_factory=set)
# Pending roster requests ("who is this new sender?") the server showed
# this turn in its <roster_requests> block — the principal's own verified
# turn only (`briefing.context.render_and_trust`). `resolve_roster_request`
# answers nothing else, so an id the model invents or reads out of text
# cannot add anyone.
trusted_roster_request_ids: set[int] = field(default_factory=set)
# Per-session override of the install's workspace mode ("solo" / "team";
# None = use the workspace setting). Evals run scenarios concurrently on
# one Executive, so they set it here instead of flipping the global. Read
# it through `memory.workspace_settings.effective_workspace_mode`.
workspace_mode: str | None = None
# Per-session override of the principal's role (None = use the
# workspace's), for the same reason: an eval scenario supplies the role
# of the principal it plays without writing the install-wide row. Read
# it through `memory.workspace_settings.effective_principal_role`.
principal_role: PrincipalRole | None = None
# Per-session voice persona slug (None = the Executive override's voice,
# else Direct), so an eval scenario can play a voice without writing the
# install-wide override that concurrent scenarios share.
voice_persona_slug: str | None = None
# The mode resolved for the turn in progress, pinned at its start by
# `workspace_settings.pin_turn_workspace_mode` (Executive.stream_chat and
# the committee path) so the tool handlers use the same mode as the
# persona and tool list. Re-resolved every turn; never an override.
turn_workspace_mode: str | None = None
# The principal's role resolved for the turn in progress, pinned with the
# mode by `workspace_settings.pin_turn_principal_role` (an empty role in
# team), so the org block, the specialists' <principal_role> tag and any
# workflow the turn starts agree even if the role is edited mid-turn.
# Re-resolved every turn; never an override.
turn_principal_role: PrincipalRole | None = None
# True for a run nobody is watching that goes through the chat loop (the
# scheduler's PROACTIVE TRIGGER dispatch). Its prompt quotes stored intent
# text, so the loop neither offers nor runs the tools in
# `schedule_tools.UNATTENDED_WITHHELD_TOOLS` — things only the principal
# decides, such as starting to track a goal.
unattended: bool = False
# On an unattended run, the teammate (not the principal) whose own turn
# queued it (``ScheduledAction.created_by_person_id``): the run is theirs
# and a fork may give it no more than that teammate's own turns get.
# None for the principal's rows and the system's.
run_for_person_id: int | None = None
# True for a turn about something private to the principal (mail from one
# of their contacts, mail they forwarded): an alert raised on it is
# private to the principal (``alerts.models.PRIVATE_ALERT_TAG``) and it
# may not draft a team-visible artifact. Set by the email poller.
private_to_principal: bool = False
# The bare, lowercased From address of the inbound email this turn is
# answering, and whether it is the principal's primary address with
# Gmail's own Authentication-Results reporting dmarc=pass for it
# (``integrations.fact_confirmation.authenticated_by_gmail``; fails
# closed). Set by the email poller only; empty / False on every other
# surface. The fact tools read them to let the principal's own
# email request a standing fact, held until a token reply confirms it
# (``orchestrator.fact_tools``) — a From line alone proves nothing.
email_from: str = ""
email_authenticated: bool = False
# Whether Gmail authenticated the From of a teammate's (not the
# principal's) inbound email: only then does the turn read the mailbox as
# that teammate (orchestrator.teammate_mail).
email_sender_authenticated: bool = False
# True when the inbound email this turn answers is from someone not in
# People (a contact or a stranger): the whole turn counts as having read
# outside content (``orchestrator.outside_content.SENDER``). Set by the
# email poller only.
sender_off_team: bool = False
# Act as me for the turn in progress (``delegation.settings.TurnDelegation``),
# pinned at its start by ``pin_turn_delegation``: whether the speaker has
# it on, whether ``ghostwrite_email`` is offered, and whether the turn has
# touched their mailbox (every audit row it writes after that is private).
# Re-resolved every turn; never an override.
turn_delegation: Any = None
# What the turn in progress read from outside and who it added
# (``orchestrator.outside_content.TurnOutside``), set by its
# ``begin_turn``; a closed turn's record holds nothing.
turn_outside: Any = None
# True when this web request carried a signed-in caller (``x-caller-email``,
# stamped by the UI proxy from the sign-in), set per turn by the chat
# route. A header-less request resolves to the principal but is no
# sign-in: Act as me needs one (or local login).
web_caller_signed_in: bool = False
# True when this web chat is shared (``session_store.shared_with``): more
# than one person reads and writes in it, so it is no private
# conversation (``delegation.settings.private_conversation``). Set per
# turn by the chat route.
shared_chat: bool = False
# True on a shared chat's turn when someone other than its owner has
# written since the owner's last message (the speaker included): the turn
# is not offered sends to people or contact writes
# (``schedule_tools.SHARED_CHAT_WITHHELD_TOOLS``). Set per turn by the
# chat route; it fails closed (True) when the history can't be read.
others_spoke_last: bool = False
# Whose documents this session reads and publishes, when that is not its
# own speaker (``artifact_records.current_viewer``): a session a workflow
# mints inside someone's turn (``executive_research``'s synthesis) is
# pinned to that turn's viewer, so what it drafts is theirs. An
# ``artifact_records.Viewer``; None derives it from this session.
documents_viewer: Any = None
# Evals and tests only (``delegation.settings.DelegationOverride``): run
# as if the speaker had Act as me, against a fake mailbox.
delegation_override: Any = None
# A replay of a graded turn (``memory.replay``): the chat loop runs as it
# would for the recorded surface and speaker, reads for real, and every
# tool that sends, posts, books, schedules, runs or changes stored state
# returns "done" and lands in ``replay_calls`` instead of running. The
# post-turn passes (memory, open loops, style, notes, the review itself)
# are skipped: nothing a replay does reaches anyone or is kept.
replay: bool = False
replay_calls: list[dict[str, Any]] = field(default_factory=list)
def add_user_message(self, content: str) -> None:
self.conversation_history.append({"role": "user", "content": content})
def add_assistant_message(self, content: str | list[dict[str, Any]]) -> None:
self.conversation_history.append({"role": "assistant", "content": content})
def get_recent_history(self, max_turns: int = 20, step_turns: int = 10) -> list[dict[str, Any]]:
"""The last ``max_turns`` turns, give or take ``step_turns``.
The window's start moves in steps of ``step_turns`` rather than one
turn at a time, so a long conversation keeps between ``max_turns``
and ``max_turns + step_turns`` turns. A window that slid every turn
would change the first history message on every request, and the
prompt cache (``orchestrator.executive._apply_history_cache_marker``)
would miss and re-write the whole conversation each time.
"""
start = history_window_start(len(self.conversation_history), max_turns, step_turns)
history = self.conversation_history[start:]
# Anthropic requires messages to start with a user turn. A chat-app
# conversation can open with the Executive's own message (a brief or
# digest it sent, ``integrations.conversations.record_delivery``).
# Dropping that would hide what the person is answering, so there a
# placeholder turn goes first; anywhere else a leading assistant
# message (left by error recovery) is dropped.
if history and history[0]["role"] != "user":
if is_rolling(self.session_id):
history = [{"role": "user", "content": CONTINUED_PLACEHOLDER}, *history]
else:
history = history[1:]
return history