AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
feat(chat): let the Executive change things in the app from chat (#541)
Rufusf36818b085bf
diff --git a/packages/core/openexecutive/api/routes/decisions.py b/packages/core/openexecutive/api/routes/decisions.pyindex 8c787d34..d1d51a23 100644--- a/packages/core/openexecutive/api/routes/decisions.py+++ b/packages/core/openexecutive/api/routes/decisions.py@@ -787,10 +787,61 @@ _DEPARTMENT_ACTION = DecisionClassSpec(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: specfor spec in (_MEETING_BOOKING, _DELEGATED_REPLY, _TAKE_THE_LEAD, _DELEGATED_ACTIONS, _DEPARTMENT_ACTION,+ _APP_ACTION,)}diff --git a/packages/core/openexecutive/architecture/prebuilt/agents.json b/packages/core/openexecutive/architecture/prebuilt/agents.jsonindex eefaa64c..a272a1f8 100644--- a/packages/core/openexecutive/architecture/prebuilt/agents.json+++ b/packages/core/openexecutive/architecture/prebuilt/agents.json@@ -1,7 +1,7 @@{"section_id": "agents","title": "Agent Council",- "markdown": "The Executive (`openexecutive.orchestrator.executive.Executive`) is a single coherent persona that fans out to specialist sub-agents via Anthropic tool use. Each specialist subclasses `openexecutive.agents.base.BaseAgent`, carrying a `name`, `domain`, and `model`, and exposes `analyze(...)`, which wraps the question in user-turn context and calls Claude through the per-call provider. That context is per call and never cached: `<company_stage>` (the stage from the company profile — specialists never see the profile itself), in solo mode `<principal_role>` (what kind of principal the advice is for, in plain words, with their title and remit — `router.principal_role_context`), `<department_memory>`, `<past_decisions>`, `<failure_cases>` (the shipped case studies, and under them the workspace's own lessons that match the call, `memory/lessons.py`), `<relevant_knowledge>` and `<conversation_context>`, outermost first. The specialist's own system prompt is a static domain constant under one `cache_control` block, so it stays byte-identical across companies and profile edits. A chat turn takes the stage from its session's profile (the one the Executive reasons over, and the one an eval scenario injects); workflow steps and the MCP server's `consult_specialist` read it fresh from the profile on disk. The role tag follows the turn's mode: a chat turn pins the role on its session with the mode (`pin_turn_principal_role`: the session's `principal_role` override, else the workspace settings) and sends it in solo and nothing in team, so the org block, every specialist in the turn and any workflow the turn starts see the same role; callers with no chat turn read it fresh (`load_principal_role`: the current session's mode and role, else the workspace's), and a failed read sends no tag rather than failing the consult. The CFO, CSO and sales prompts key their advice on it: for a bootstrapped, self-funded or solo company they drop venture fundraising benchmarks and work from cash, and raise only if the founder wants to.\n\nRouting uses one `consult_specialist` tool. When to call it is spelled out in the persona's Domain Expertise section (\"Going deeper\") and in the tool's own description: any question that asks for judgment in a specialist's area (a decision, plan, analysis, negotiation, hire, contract term, pricing or fundraising move, board message, or a department's own targets and stance, since the specialist holds that department's memory) is consulted before the answer, several at once across areas; lookups in mail, calendar or documents, scheduling, status checks, routine drafting and questions about how the Executive works are answered without one. Chat eval scenarios hold this: `required_routing` names specialists the turn must consult and `no_routing: true` says it must consult none, and the runner fails a scenario that misses either (`evals.scenarios.routing_check`). Beside it the Executive carries two skill tools, `search_skills` and `load_skill` (skills are shown to users as **playbooks**, and every playbook belongs to a workflow: one that follows it, or its own Quick workflow). Chat finds and reads playbooks but never creates or changes one: work worth repeating is offered as a workflow through `draft_workflow`, with the method written into its steps, because workflows read playbooks at run time (approved scheduled ones included) and this loop also runs on inbound email and chat, so only a person can change what a workflow follows. A hidden built-in is invisible to search and load; each `search_skills` hit lists the `workflows` that follow it, Quick ones included, and the persona routes \"the finished deliverable\" to that workflow and quick or partial asks to the playbook inline; Tool calls made while proactive work is tagged (scheduler dispatch, reflection, research, alert review) feed the Attunement outcome ledger. Goals have three tools: `list_department_goals`, `update_department_goal` (progress the user reports) and `create_goal` (a new goal the principal states, filed under an area by slug or title and creating the area when none matches — see Org). `create_goal` runs only for the principal on a verified surface, and no unattended run is offered it: the tools in `schedule_tools.UNATTENDED_WITHHELD_TOOLS` are dropped from reflection's and research's toolkits by `unattended_toolkit`, and from the chat loop when its Session is marked `unattended` — the scheduler's PROACTIVE TRIGGER run, whose prompt quotes stored intent text; a call the model emits anyway gets an error tool_result. `record_decision_outcome` records how a past decision turned out — the weekly review lists decisions older than 30 days with no outcome as `[decision N]` — writing `decisions.outcome` (`episodic.update_decision`) and auditing the rationale; it has `create_goal`'s gate (the principal on a verified surface only; everyone else gets an audited refusal) and is in `UNATTENDED_WITHHELD_TOOLS` too. A missing or unknown id returns the decisions still waiting on an outcome, so the model can retry with the right one. Its schema is static; the solo persona has one line on it, and team mode learns it from the tool description, so the team persona is byte-identical. Attunement adds `list_open_loops` (what a person owes — everyone's for the principal only in a private conversation, otherwise the caller's own) and `close_open_loop`, which only closes a loop when the turn's resolved speaker is the principal or the loop's owner — an unrostered sender, a signed-in web user not on the roster, and unattended sessions are refused. `assign_open_loop` opens one on request (\"ask Ben to send me the Q3 numbers by Friday\") for the principal or a rostered teammate on a verified surface — never an email, a turn private to the principal or an unattended run, which are also withheld the tool — and only when `task` appears verbatim in what the speaker typed this turn, at most 5 per turn; that turn's extraction pass then opens no second loop for the same owner. The owner is told once on their own channel when someone else assigns it, and the result's `notified` says how that went, so the Executive reports it rather than messaging them as well. The roster write tools (`upsert_person`, `archive_person`, `set_department_head`) are the principal's alone, and only on a surface that verified the speaker — the web chat, the principal's own Slack or Discord, a channel whose adapter verified the sender itself (`Session.speaker_verified`, with the `caller_person_id` it resolved, never on a turn an email started), or a private Telegram chat when `TELEGRAM_WEBHOOK_SECRET` is set to a value Telegram can send (Telegram identifies the chat rather than the sender, and without that secret its webhook accepts anyone's update). A teammate, an email (even from the principal's address), Google Chat, the CLI, the MCP server and unattended runs get `status: refused` (audited, and no action chip), because a team member's People row is also the web sign-in and outbound-email allow-list. `upsert_person` takes `kind` (`team` / `contact`; a new person defaults to `contact` in solo mode, an update keeps the current kind) and `email_aliases` (other addresses the person writes from — the full list, replacing the current one; they match mail and may be emailed but never sign in, and one already on someone else is refused), and after every write any pending roster request whose sender now matches someone is closed and its held messages replayed. `resolve_roster_request` answers a **roster request** — someone not on the People list who wrote in and is waiting (see Org): `approve` (a new person; `kind` defaults to team for a company-domain sender, else contact, when the principal did not say), `link` (someone already listed, by `person_id`; `replace_channel_id` only when the principal said so) or `decline`. It has the roster tools' gate (the principal on a verified surface; audited refusal otherwise), is in `UNATTENDED_WITHHELD_TOOLS`, and answers only an id in `Session.trusted_roster_request_ids` — the ids the server printed that turn in a `<roster_requests>` block (`briefing.context.format_roster_requests_for_prompt`, up to 10 pending requests), which `render_and_trust` appends to the `<briefing>` digest on the principal's own verified turn only and records on the session in the same step, so an id the model invents or reads out of a message adds nobody. Each line is server-derived — id, channel, address or account id, the sender's name sanitised and marked unverified, a company-domain hint, the message count — and never what they wrote. The block rides in the **user turn**, like the digest, so the cached system blocks are unchanged; the tool definition is static, and the new tool only extends the sorted tool list. The web chat route resets the trusted set every turn, and a resolved id is removed from it. and `list_people` returns both kinds with `kind` — contacts only on the principal's own verified turn (they are private to the principal; anyone else gets the team as if no contact existed) — while `lookup_person` searches the team only. `ask_about_person` reads a person's peer memory fully only on their own verified turn; anyone else's answers only to a verified principal or teammate, and only when that person turned on \"Share my work style with the team\", framed to how they work and never their view of a colleague, and otherwise returns the same \"hasn't chosen to share\" result whether or not anything is known. A teammate's own mail with the Executive is theirs the same way: every mailbox call the model makes through the MCP gateway (Gmail or Outlook, by `call_tool`, from a script, or a workflow step run from chat) passes through `orchestrator.teammate_mail`. A search excludes every other teammate's address server-side, except on mail the reader is also on, and is filtered again entry by entry; any other call that names a message or thread (read, attachment, reply, forward, label) must use an id a filtered search returned to the same reader in this conversation (`Session.mail_ids_seen`) or the inbound email the turn answers; reads are filtered message by message, so a message naming another teammate is left out unless the reader is in its From / To / Cc; a reply that would quote such a thread, or an Outlook forward, reply or attachment read of such a message, is refused; and a conversation in which a teammate other than the principal was shown their own mail becomes theirs alone, as Act as me's do. Outside mail and the reader's own are untouched; an email turn reads as its sender only when Gmail authenticated it, and any other unverified reader sees no teammate's mail, a background run the model drives reads as the principal and a workflow step outside any session as nobody, an Outlook inbox rule that forwards or names another teammate is refused, and the poller and the brief, which read the mailbox themselves, are unaffected. Their own chats are theirs too: every audit row of a teammate's verified turn is theirs (`people_tools.teammate_turn_owner`, see Audit; the principal sees the actions, never the words), and a teammate's web chat or DM opens for them alone (`chat._session_access`), the principal included. The same verified-principal rule, as `people_tools.contacts_reachable_now()`, decides whether a turn may reach a **contact** at all: `message_person`, the raw DM tools, `create_calendar_event` / `create_instant_meeting` attendees and the MCP gateway's Gmail / Calendar / Drive / OneDrive gates treat a contact exactly like an unknown person on every other turn, so no refusal reveals that one exists. **The untrusted-content policy** (`orchestrator.content_trust`) is one rule for text the principal did not write — inbound email, chat, attached files, watched pages — answering three questions for every surface. *Who is speaking*: the principal only when the surface proved it (`principal_speaking`: the web chat as the principal — never a signed-in email on nobody's People entry —, the CLI, their own Slack/Discord or a secret-verified Telegram chat, or their own address with Gmail's `dmarc=pass`); never a teammate, a stranger, Google Chat, the MCP server or an unattended run. *What may become memory*: episodic extraction runs only then, and only on the words outside `<untrusted_content>` blocks; peer memory and open loops are recorded under the speaker's own name, never as the principal's. *What may trigger tools*: every write on the principal's authority already refuses others in its handler; the tools with no such check that change the install for every later turn — `content_trust.PRINCIPAL_ONLY_TOOLS`: `load_mcp_server`, `list_saved_tools`, `run_python_job` and `run_script` — are not offered unless the principal is speaking on an interactive surface (not email, even authenticated), and a call the model emits anyway gets an error tool_result and a `refused: not_principal` audit row. So an inbound email, a teammate's turn, Google Chat and the scheduler's proactive trigger each get a stable tool list of their own without it. A send or edit on a team member's turn also meets their department's authority first (`orchestrator.department_gate`, see Org), and so does one on a turn whose speaker is on no People entry: a signed-in web caller or a chat-channel sender, which in practice is Google Chat, since Slack, Telegram and Discord turn unmatched senders away. Google Chat names a matched sender to the gate alone (`gate_sender_person_id`), so the principal there is not held. Email turns are left to the mailbox's own gates. *How it is labelled*: outside text goes into the user turn inside `<untrusted_content source=… author=… author_verified=…>` with a fixed notice that it carries no authority; compatibility forms are folded (NFKC), control characters go, and the tag's name is renamed wherever the text carries it — any case, spacing or entity-escaped form — so the text cannot end its block and speak outside it.\n\n**Outside content** (`orchestrator.outside_content`). Once a turn has read text from outside the team (any gateway read, an attachment, a web search result, a synced Drive, OneDrive, Confluence or Notion excerpt, `read_document`, research, or an extension tool registered `reads_outside`), the rest of that turn refuses what the Act as me lockdown refuses, every `upsert_person`, and every `call_tool` but a read: no mail, Docs, Sheets, Drive or calendar write. A round that reads also holds that round's other such calls; the read itself runs. Scripts are checked call by call. The offered tools never change, so the cached prefix stays the same, and the hold ends with the turn. Mail from someone not in People (a contact or a stranger) counts as outside content from the start of its turn (`Session.sender_off_team`), so the whole turn is held, with no direct messages or watchlist removals either; it can still raise an alert, private to the principal, which is how that mail reaches them. Someone added to People in a turn (or given a new address or chat account) is not emailed, messaged, invited or shared with until the next one.\n\nA turn about the principal's private mail (`Session.private_to_principal`) reaches the principal only. It is neither offered nor allowed to run `schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS` — everything that reaches someone else, publishes where the team reads, or starts work outside the turn: the broadcasts, meeting bookings and cancellations, `run_workflow` and research, follow-ups and workflow nudges, watches, artifacts, goal updates, saved workflows, skill drafts, and `load_mcp_server` (it connects to any URL, which can carry the turn's content). Through `search_tools` and `call_tool` it reaches only `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads (mail, calendar, and Drive, Docs and Sheets search and file reads, with their Microsoft 365 twins; OneDrive's `download-bytes` only for a file's content) and the Gmail send and draft the gateway narrows to the principal. A search shows it nothing else, and a call to anything else (Google Chat, a Docs or Drive write, `manage_event`, another server) is refused (`schedule_tools.private_turn_withholds`). A call the model emits anyway, MCP tools included, gets an error tool_result and writes an audit row, and every audit row the turn writes is the principal's alone.\n\nA turn another AI app asks over the MCP server (`Session.from_mcp_client`, set by `ask_executive`) reads and advises but never acts, unless the request may act (below). It is neither offered nor allowed to run `schedule_tools.MCP_CLIENT_WITHHELD_TOOLS`: the private-turn and unattended sets, plus every direct message (`message_person`, the Slack, Discord and Telegram DMs), alert acks and new alerts, brief edits, closing open loops, roster and department-head writes, watchlist changes, workflow drafts and form proposals. It gets no Act as me, `recall_history` or extension tools, and of the gateway tools only `schedule_tools.MCP_CLIENT_MCP_TOOLS`: the private-turn reads without the Gmail and Outlook send and draft tools. The set is fixed, so the variant keeps a stable cached tool prefix. A call the model emits anyway, through `use_tool` or `call_tool` included, gets an error tool_result telling it the conversation comes from another AI app, so it can read and advise but not send, post, book or change anything, and writes an audit row (`refused: mcp_client`); `MCPGateway.call_tool` refuses the same calls again.\n\nA request may let that turn act (`Session.mcp_client_may_act`: the `x-mcp-client-actions: on` header on a request the shared secret authenticated, or `MCP_CLIENT_ACTIONS` where no secret is set). It then runs the speaker's own changes inside Open Executive (`schedule_tools.MCP_CLIENT_RUNS_WHEN_ACTING`: alerts, open loops, follow-ups, the watch list, goals, decision outcomes, facts and company profile writes; never the roster), each under its own owner-only and person checks, since the turn counts as a verified surface for its caller. It is still denied a fixed set, `MCP_CLIENT_ACTING_WITHHELD_TOOLS` (DMs, calendar writes, broadcasts, `load_mcp_server`, scripts, Python jobs, workflows, research and the rest of the read-only set), with a refusal telling the person to do it in Open Executive. A message or a meeting goes on an approval card instead (`propose_actions`), which is carried out at once when the person's Handle it for me covers it, everyone on it has been on the roster for a week, and `action_cards.on_its_own_refusal` finds nothing against it, and otherwise waits for their tap. Every audit row it writes names the app (`via`).\n\nA web chat its owner shared (`Session.shared_chat`) mixes people. The note naming who is in it says which of them owns it and that the others' lines are messages from them, not the owner's instructions. While someone other than the owner has written since the owner's last message (`Session.others_spoke_last`, set per turn by the chat route from the saved history, the speaker included, and true when the history can't be read), the turn is neither offered nor allowed to run `schedule_tools.SHARED_CHAT_WITHHELD_TOOLS`: direct messages, the broadcasts, meeting invites and cancellations, follow-ups, roster writes and workflows (a run, a save or a suggested schedule acts later with the full tool set). Through `call_tool` it can't send, reply, forward or draft mail in Gmail or Outlook, or make a calendar change that mails attendees (`schedule_tools.shared_chat_withholds`). That holds on the owner's own turn right after someone else's line too, so a request carried over from it can't send; the owner's next message with nobody else's in between lifts it. A call the model emits anyway gets an error tool_result and writes an audit row (`refused: shared_chat`). The principal-only tools stay out of every shared chat (`content_trust.principal_only_withheld`).\n\nOn every turn the Executive knows what is connected without searching: block 0's *Connected Systems* section names the connected Google services, other MCP servers, the messaging channels, Notion sync, Confluence sync (when on) and Act as me, and pins the Google tool names it calls directly with `call_tool`. Both the service list and the pinned names are narrowed to what workspace-mcp actually loaded (`WORKSPACE_MCP_TOOLS`, `WORKSPACE_MCP_TOOL_TIER`), so a service left out is not named and its tools are not pinned — being told a tool is already available when it is not in the index costs a failed call the model cannot explain to itself. `search_tools` is for anything not listed. When work repeats over many items, the Executive can also call `run_script` (`workflows/step_script.py`, offered when the gateway runs, unless `CHAT_SCRIPTS=false`, and only on the principal's own turns — `PRINCIPAL_ONLY_TOOLS`, withheld on an unattended pass too, because it spends the turn's whole call budget on code the model just wrote): one short Python script, run in a sandboxed Monty worker with no files, network or environment, whose only reach is the gateway tools `call_tool` could reach (those `search_tools` has returned; the gateway keeps that set for its own process-wide session, not per conversation). Each call it makes is a `call_tool` in every way that matters — the gateway's discovery, deny-list and recipient gates, Take the lead's gate on an unattended run (or the department gate on a team member's turn, see Org), and the same action chip and `tool_invocation` row (marked `via: run_script`, `ok: false` when it raised), as each call happens; the script itself gets a `kind: script` row with its source and result. Its wall clock is half the turn's deadline, so a long script ends with the list of calls it made rather than being cut off with the turn, and a stopped turn closes it and its worker. A turn private to the principal is not offered it, and the Act as me lockdown withholds it whole. Besides gateway tools, a chat script may call a fixed list of the Executive's own tools (`step_script.CHAT_OWN_TOOLS`: reads, alerts, open loops, goals, the watch list, follow-ups, `message_person`, `upsert_person` — nothing that broadcasts, books calendars, edits memory or skills, or starts workflows or research), each only when the turn is offered it and through the turn's own handler (Take the lead's gate included), with the same chip and a `kind: skill`, `via: run_script` audit row. A direct call needs a `tool_use` each, so a turn's scripts share a budget instead: `CHAT_SCRIPT_MAX_CALLS` (default 200) calls in all, and per-turn caps on own tools that could otherwise act in bulk (`CHAT_OWN_TOOL_CAPS`: `message_person` 10 — messaging the whole roster would be a broadcast — `upsert_person` 25, `create_alert` 50); a refused call tells the model to say what is left. A call stopped mid-flight by the script's clock or the turn still gets a `cancelled` audit row, since it may have run. Because every round re-reads the conversation, the loop also nudges at the moment of choice: after a round whose results include a list of five or more items (`step_script.lists_many`), with `run_script` on offer and not used that round, it adds the constant `FANOUT_HINT` as a text block in that round's user message (never a cached block), once a turn, pointing the per-item work at one built tool. For library work on files (PDFs, spreadsheets, charts, images) the chat also has `run_python_job` (see Workflows → Python jobs): Python with a fixed library set in a Deno-isolated WebAssembly sandbox, fed Knowledge files by name, the message's own attachments as sent, or text it already holds, and able to keep a job that worked as a Custom tool, with result files linked for the principal to download; it is offered only on the principal's own turns and only where the sandbox is installed (not offered otherwise, so the tool prefix stays fixed per process). Agent Activity shows each run as one \"Built tool\" card (debug event `script_run`: ok, the calls it made, how many, how long, and the kept or reused tool's name). The persona's tool-building section is present only when chat scripts can actually run (the setting and Monty installed). `TOOL_BUILDING_ADDENDUM` in the cached persona tells the Executive when to build a tool — a job that looks something up and then checks or acts on each result, paged results, more than about ten items, or an answer that needs three or more reads (find, open, read; the tool returns only what answers the question, not whole documents, and only what is about to be edited or quoted at length is read in full), while a handful of items already named go as direct calls in one turn — and never to say it has none, and to talk about it as building a tool or doing it in one go. On the principal's own verified, interactive turns, a script that works can be saved as a named tool (`save_as`; elsewhere the script runs but is not saved) and run again with `run_script(tool=…, inputs=…)`; `list_saved_tools` (a constant definition, in `PRINCIPAL_ONLY_TOOLS` with `load_mcp_server`, so offered only while the principal is speaking on a verified, interactive surface; `run_script(tool=…)` is refused on any other turn) lists them, and each call a saved tool makes is a gateway call like any other (see Workflows → Saved tools). The tool's definition is a constant, so the cached tool prefix does not move. Multiple parallel `tool_use` blocks in a single assistant turn fan out concurrently through `router.route_parallel`, each running its own domain-filtered ChromaDB query (3 built-in and 2 company chunks by default, see the RAG section) before the specialist sees the question. The fan-out is failure-isolated per call: a specialist that raises or returns no text becomes an `UNAVAILABLE` tool_result (`router.specialist_unavailable_result`) instead of failing the whole turn, and its area — \"finance\", \"legal\", never the specialist's name — is reported to the user under the web reply, or by the Executive in its reply on other channels, unless another call to it answered that turn. A failed specialist does not count as consulted, so it takes no committee seat. Cancellation (Stop) still propagates. The Executive then synthesizes the returned analyses into one reply.\n\n`remember_fact`, `forget_fact` and `update_company_profile` (`orchestrator/fact_tools.py`) make a correction stick: the first two keep or retire a standing fact in `memory.facts`, and the third changes one field of the company profile. They share `record_decision_outcome`'s gate (the principal on a verified surface, an audited refusal for everyone else) and are in `UNATTENDED_WITHHELD_TOOLS`. `remember_fact` alone also admits a rostered teammate on a verified surface (web signed in, their own Slack or Discord): the fact is stored attributed (`recorded_by_role=\"teammate\"`, rendered `(per <name>)`), and is held as a `proposed` row (`awaiting_approval`) until the principal approves it, unless the principal marked that teammate trusted (\"needs my approval\" off; on by default) — and even then when it would replace the principal's fact. All three are also in `PRIVATE_TURN_WITHHELD_TOOLS`, since what they write or retire is read on everyone's turns. On the principal's own authenticated email (primary address, with Gmail's own `Authentication-Results` reporting `dmarc=pass`, not forwarded) the three tools check the request as usual, then hold it as `awaiting_confirmation`. It applies only when the principal replies to a one-time token emailed to their own address (`integrations.fact_confirmation`); the split into a check step and an `apply_*` step lets chat and the confirmed reply share one apply path. Each write also needs a `source_quote` found in the speaker's own words this turn. The active facts reach every specialist as a `<standing_facts>` user-turn tag: `route_to_specialist` reads them (None → the store, \"\" → none) for chat consults and workflow steps alike, and `BaseAgent.analyze` places the tag next to `<past_decisions>`, never in the cached specialist system prompt.\n\nThe ten entries in `SPECIALIST_REGISTRY` (`openexecutive.orchestrator.router`):\n\n| Key | Agent | Domain |\n| --- | --- | --- |\n| `cso` | `StrategyAgent` | strategy |\n| `cfo` | `FinanceAgent` | finance |\n| `chro` | `HRAgent` | hr |\n| `gc` | `LegalAgent` | legal |\n| `coo` | `OperationsAgent` | operations |\n| `cmo` | `MarketingAgent` | marketing |\n| `cpo` | `ProductAgent` | product |\n| `sales` | `SalesAgent` | sales |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5-5`; the deep-reasoning tier (CSO, CFO, GC, Board) runs on `DEEP_REASONING_MODEL`, `claude-sonnet-5-5` by default, with adaptive thinking; routing/fast classification uses `claude-haiku-5-5`. Requests are fitted to the model's generation on the way out (`feature_gate.fit_claude_generation`): 5-generation Claude models never receive `temperature` / `top_p` / `top_k`, and Haiku 5.5, which thinks unless told otherwise, gets thinking turned off when the caller asked for none. The Council's **Deep reasoning** toggle is honoured on Claude Opus/Sonnet (direct or via OpenRouter) and on any OpenRouter model whose live catalog entry supports `reasoning` (today all OpenAI, Gemini, DeepSeek and Grok entries; not Llama) — the request translator turns Anthropic adaptive thinking + effort into OpenRouter's `reasoning` parameter. It is a silent no-op on models that can't reason, and disabled for Haiku, which rejects adaptive thinking. A PDF `document` block is translated too: it becomes an OpenAI `file` part, and OpenRouter requests carrying one add the `file-parser` plugin (`native` for models whose catalog entry lists `file` input, else `PDF_OPENROUTER_ENGINE`, default `mistral-ocr`). `FeatureSpec.supports_pdf_input` gates it per model — off for a local server unless `LOCAL_PDF_INPUT` — and a gated-off PDF becomes a text note rather than vanishing. The Council picks a model in two steps: a **Provider** dropdown (Anthropic, OpenAI, Google, Meta, DeepSeek, xAI, Local, …), then a **Model** dropdown limited to that provider, with readable names (\"Claude Opus 5.5\") and the raw id and serving route shown underneath. The Anthropic group combines the direct Claude models (`claude-fable-5-1`, `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5-5`, `claude-sonnet-5`, `claude-haiku-5-5`, `claude-haiku-4-5`) with any Claude generation that exists only on OpenRouter, and never lists a model twice. With `OPENROUTER_ENABLED`, the non-Anthropic entries come from OpenRouter's live `/models` catalog (fetched at startup, refreshed in the background, filtered to tool-capable paid text models from an allowlisted vendor set), falling back to a built-in snapshot if the fetch fails. Every Council agent also takes **additional instructions** (`agent_overrides.instructions`): text appended after its prompt by `agents.overrides.append_instructions` inside an `<additional_instructions>` block. `BaseAgent.base_system_prompt()` is the built-in prompt or its full replacement (what the Council's editor shows); `effective_system_prompt()` is that plus the instructions (what every call sends), and the Executive gets the same text through `build_system_blocks(persona_instructions=…)`. Unlike a replaced prompt, instructions leave the agent on its built-in prompt, so prompt improvements keep reaching it. A **Quality** choice above the agents (`agents.presets`) sets every agent's model and deep reasoning at once: **Fast** puts every agent on a small model (`claude-haiku-5-5`, else `claude-haiku-4-5`) with deep reasoning off, **Balanced** returns each agent to its built-in defaults, and **Thorough** puts the Executive and the domain specialists on the largest allowed model (`claude-opus-5-5`, else `claude-opus-5`) with deep reasoning on where the model supports it, leaving triage and the helpers below on their defaults. Presets change quality only; they never cap spend. Each preset resolves against the install's model allowlist at request time and is offered only when one of its models is allowed. Applying one writes ordinary per-agent overrides (model and deep reasoning only), so history, rollback and later per-agent edits keep working; an agent changed on its own afterwards shows as **Custom**. Each Council agent has a **visibility**: `core` for the Executive and the domain specialists (`BaseAgent.visibility = \"core\"`, which a new specialist must declare) and `internal` (the default) for triage and the helper agents below. Thorough moves only core agents. The Council opens in a **simple view**: the Quality choice, the voice picker, and only the core agents, each with its additional instructions and a model badge. **Show all agents** lists the internal ones too, and **Advanced** opens the full page (the browser remembers the choice). Eight Council-only agents are model/prompt-overridable in the UI but NOT callable via `consult_specialist`, because they are deliberately kept out of `SPECIALIST_REGISTRY`: `quality_judge` (committee review), `utility_fast` (gates, titles, decision parsing), `research` (the `executive_research` fan-out), `fixture_generator` (invents demo companies), `engagement_intake` (models a real client from intake material), `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments), `workflow_designer` (runs the conversational New workflow wizard on `/jobs/new`: searches the available tools, asks clarifying questions, then drafts a validated dynamic-workflow definition for the user to review), and `workflow_actor` (runs a workflow's `action` steps: a bounded tool-use loop limited to the tools the user approved for that step). `fixture_generator`, `engagement_intake` and `onboarding_interviewer` share one shape — a forced tool call producing a whole company, validated for referential integrity, with a single repair retry — but opposite epistemics: the fixture author invents, the other two extract and leave unstated facts empty rather than guessing. When the workspace is in solo mode, `onboarding_interviewer`'s first user turn is prefixed with a short hint (`interview.solo_hint(role_kind)`, one static constant per role kind from the onboarding role step): the draft names only the principal, as principal, and no departments; an owner is asked about the offer, customers, pricing, cash and runway, an in-house executive about their organisation (drafted as the company — their employer), function, remit, manager, team size as context and what they are measured on, an independent about their practice, clients and pricing, and with no role given the role-neutral `SOLO_HINT` asks which they are. The hint rides in the user turn and the tool array is unchanged, so the cached system prompt and tool prefix are the same in both modes.\n\n**Voice.** The Executive answers in one voice persona, substituted into block 0 at `{VOICE_PERSONA}` (`personas/loader.get_active_body`) from the Executive override's `voice_persona_slug`. Three general voices ship in `personas/builtin/`: **Direct** (`default`, the slug used when none is set: answer first, brief and decisive), **Supportive** (a warm coach who explains the why and checks how the plan sits) and **Analytical** (numbers first, options and trade-offs, then one recommendation). They are offered by a shared picker in setup (`/onboard`, after the workspace choice) and in Settings → Executive, which saves through `PATCH /agents/executive`; a built-in voice's frontmatter carries the picker's one-line `description` and `sample` reply. The named-executive voices are marked `legacy: true`: the picker hides them, but they still load, so an install that picked one keeps it, and the Agent Council lists them under \"Legacy voices\". Voice files hold disposition only; the response-length ladder lives in `prompts/executive_persona.py`, and a test keeps numeric length rules out of every voice file. An eval scenario may set `voice_persona` to answer in a voice; it rides on `Session.voice_persona_slug`, which wins over the override for that session only.\n\nOne more structured-output utility agent sits beside `triage`: `openexecutive.agents.alert_review.AlertReviewAgent` (routing model, one forced `emit_alert_reviews` tool call, never raises). The alert review job hands it a batch of open alerts with evidence and gets back, per alert, a verdict (relevant / changed / resolved / stale), a confidence, the evidence it relied on, a one-line note, why-now, an optional deadline, and a recommended move (none / route / nudge / escalate / draft / suggest_workflow / merge / close) with its parameters. Like `triage`, it never mutates state — `alerts.review.apply_verdict` executes the verdicts deterministically within authority, so the model's job is judgment, not action.\n\n**Solo mode.** When the workspace (or the turn's session) is solo — one person using Open Executive for themselves — the Executive works for that one person, the principal, whatever their role: they may run their own business, lead a function inside a larger organisation, or work independently, and the persona reads which from the context instead of assuming it — the role lines under \"Your Principal\" in the org block, when the principal gave their role (workspace settings: kind, title, reports to, remit, measured on). Its persona swaps the team sections (\"You Are a Member of This Executive Team\", \"Choosing Who to Tell\", \"Departments & Org Coordination\") for \"You Work for One Person\", \"The People in Their World\", \"Who Hears From You\" and \"Goals and Areas\". Solo means only the principal uses Open Executive — not that they have no people: their manager, direct reports, peers, clients, investors and board are contacts. The Executive helps the principal work with them (a 1:1 or review prep, an update or budget case for their manager or board, a negotiation) but does not coordinate them, contacts them only when the principal asks and only if they are a contact, and never offers to loop the principal in. Every specialist stays relevant — HR for the principal's own reports, board and investor communications for reporting upward. Goals are grouped by *area* (the tools' `department_slug` is the area's slug). The chat loop withholds `send_department_message`, `send_company_broadcast` and `set_department_head` from its tool list, and a call to one of them anyway gets a JSON error tool_result instead of running. The mode is resolved once per turn and pinned on the session, so the persona, the org block, the tools and every tool handler agree — a switch made mid-turn applies from the next turn. Team mode is unchanged.\n\nEvery specialist *advises* — each returns domain analysis the Executive synthesizes into one voice. None of them act on the company's behalf; the side-effecting tools in the main loop (schedule, people, departments, broadcast, watchlist, workflows) belong to the Executive, not to a specialist.\n\n`recall_history` (Always in the loop, `orchestrator.history_tools`) reads the speaker's own notes, on the same terms as `ghostwrite_email` below: its own registry, offered only on a verified turn in a conversation private to them with their switch on; its `due` flag lists only dated notes, soonest first (see Memory). The ghostwriter below also gets the writer's notes from mail every recipient was on, as a consistency check (`<writer_noted>`).\n\nThe morning reflection, which has no question to look up and no specialist to consult, gets one more read-only tool of its own: `search_knowledge` (`orchestrator.knowledge_tools`), the same knowledge lookup a chat turn makes, for what the company's documents say about a customer, contract, price or policy before it acts.\n\nA fifth, `remind_me` (`orchestrator.reminder_tools`), sets a plain-text reminder sent to the speaker alone when it is due; it opens no mailbox, so it never locks a turn. A sixth, `propose_actions` (`orchestrator.action_card_tools`), does nothing itself: it leaves the speaker a card of up to five actions (a meeting, a message, a new contact) that happen only when they tap Approve, so it stays on after a turn read mail; it is where what an email itself asks for goes, since that is never done on the email's say-so. Four read-only tools beside it read the speaker's own mailbox on the same terms — `search_my_email`, `read_my_email`, `read_my_email_attachment`, `my_email_awaiting_reply` (`orchestrator.mail_read_tools`) — and `my_calendar` their own calendar while Read my calendar is on, capped per turn, other people's messages and attached files returned as untrusted blocks (see Act as me). Beside them, `save_my_email_attachment` copies one attached file, when the speaker asked in their own words, into a fixed folder of the Executive's own Drive or OneDrive and shares it with them alone, every call built in codeOne tool writes under someone else's name, and it is fenced in code rather than the prompt. `ghostwrite_email` (**Act as me**, `orchestrator.delegation_tools`) writes an email as the person the Executive is speaking with and saves it as a draft in their own mailbox, Gmail or Outlook (`delegation.gmail.gmail_for` picks the client by the person's credential); chat never sends it (the person sends it themselves, or taps Send on its card). It lives in its own registry, never `_ALL_SKILL_TOOLS`, so reflection, research and workflow toolkits can never carry it. The chat loop adds it only on a turn `delegation.settings.pin_turn_delegation` offered it to — the principal, or a team member once the owner lets them, with it on, verified, in a conversation private to them (the web chat, a Slack or Discord DM, a verified private Telegram chat), on an attended turn — and builds that turn's handler map from both registries, so on any other turn a call to it is an unknown tool. From the round that calls it until the turn ends, the dispatch guard refuses only what opens an outside address, runs a script or workflow, or posts to everyone (`delegation.lockdown`), without changing the offered list; messages and invites to the roster, follow-ups, facts in the person's own words and a contact they name still run, each fenced in its own path. A later turn in the conversation stays private to its owner but holds nothing: the person asking again, having read the reply, is their own request. A contact add the lockdown refuses becomes an approval card in the chat instead (`propose_actions`). Recipients are chosen in code, never by the model (a draft's new email may go to any address, named back to check when it is neither on the roster nor typed), and the text comes from the **ghostwriter** (`delegation.ghostwriter`), a tool-less call with a constant prompt plus the person's \"How I write\" profile. The ghostwriter is deliberately not a Council agent: the Council's edit routes have no principal check. See **Act as Me (Delegation)**. A second tool joins the same way: `recall_history` (`orchestrator.history_tools`, Always in the loop) reads the speaker's own notes of what they said, by email or in chat. It has its own registry and per-turn handler map too, and the loop adds it only when `history_tools.recall_person` finds the speaker verified, in a conversation private to them, on an interactive turn that isn't private to the principal, with their notes switch on. It doesn't need Act as me. After every chat turn the Executive also hands the speaker's own words to `history_chat.schedule_chat_notes`, which takes notes in the background when their switch is on and the surface verified them (see **Memory**). A meeting `create_calendar_event` proposes works the same way when the person chatting is the one who approves it: its chip carries the `decision_id` and the chat shows the meeting card (Approve, Edit, Dismiss) under the reply, while the briefing keeps it too. A tool result held for someone else's approval (`waiting_for_approval`, the department gate) gets a *Waiting for approval* chip, never a done one.\n\nThe Executive can also launch *any* workflow conversationally: `orchestrator.workflow_run_tools` adds `list_workflows` (the launchable catalog with each workflow's inputs) and `run_workflow` (runs a built-in or custom workflow to completion and returns its artifact, checkpointing approval gates as `awaiting_human`). `run_workflow` runs the weekly review, and in solo mode the morning brief, only for the principal on a verified surface (`Workflow.principal_only_modes`, `create_goal`'s rule); anyone else gets an audited refusal that does not name the rule. A run whose `result` event reports `private_to_principal` (the morning brief on the principal's own verified turn, when it read their private rows) still returns its artifact into that turn, but the stored run keeps `persistence.PRIVATE_RUN_ARTIFACT` instead of the text, since run history is readable by everyone signed in. This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nDeliverables are first-class too. `orchestrator.artifact_tools` gives the Executive three tools: `draft_artifact` publishes a memo, web page (`html`), Word document (`docx`), spreadsheet (`xlsx`, from structured `sheets`) or a `link` to something it created in one of the principal's connected apps through the generic MCP gateway (`search_tools` → `call_tool`, any server — no vendor is named), and returns the artifact's id and link; `list_artifacts` and `get_artifact` let it find and reread its own past work (drafts and workflow outputs alike, through the same `artifact_records` read model the API uses). Every artifact belongs to someone: a draft to the person whose turn published it (`artifact_records.current_viewer`; with nobody speaking, the scheduler or the CLI, the principal), and a run someone started by hand to them, while scheduled runs are the team's. The tools, the recall, `message_person`'s link and mail attachments only ever reach the speaker's own (a link is refused when the recipient couldn't open it), not even the principal sees a teammate's, and a speaker who isn't on the People list publishes nothing. A workflow's own session inside someone's turn (the research synthesis) is pinned to that turn's viewer (`Session.documents_viewer`). Revising is `draft_artifact(supersedes=<id>)`, which archives the earlier version. When the principal asks for a deliverable the tool is always used; the \"quiet is the right default\" bar applies only to unprompted drafts. The format enum is a hard-coded sorted tuple so the cached tool schema stays byte-stable. Delivery: `message_person(person_id, text, artifact_id?)` appends the artifact's title and a `UI_BASE_URL/artifacts/<id>` link (through the same outbound guard as any DM; the link needs Open Executive access), and a Gmail send/draft can attach the file itself by `artifact_id` — see Integrations.\n\n**Extensions** (`orchestrator.extensions`). An install can add chat tools and kinds of document without changing this code. `OPENEXECUTIVE_EXTENSIONS` names Python modules. The first turn, or the first Documents read, imports each one and calls its `register()`. A module that fails is logged and skipped. `register_tool` takes an `ExtraTool`: a definition, an async handler, an optional `tool_groups` group (new or existing) and an optional chip. It refuses a name the loop already knows (`executive.builtin_tool_names`). An extension tool is never in `_ALL_SKILL_TOOLS`, so reflection, research and the synthesis never see it. The chat loop adds it per turn, like the Act as me tools, but never on an unattended run, a turn private to the principal or to a speaker who isn't on the People list (mail from a stranger), and only where its own `offered(session)` says. That predicate depends only on the kind of turn, so each kind of turn keeps one cached tool list. Act as me's lockdown refuses it once the turn has read the owner's mail, because it is unclassified and the lockdown fails closed, unless it was registered with `after_mail_read=True`: a tool that only reads the install's own data and carries nothing the model wrote anywhere outside. Its chip goes through `action_chips.summarize_action`, which applies the same no-chip rules for an error or refusal and keeps a link to a path inside the app. `register_collection` adds a kind of document: a drafted artifact tagged `collection:<name>` carries that collection on its record. The Documents page gives each collection its own filter. The collection's `on_change` hears about archive, restore and delete before they happen; if it raises, the change does not happen. `draft_artifact(supersedes=…)` refuses a collection's document. The alert pipeline strips `collection:` tags, so only the extension's own code files a document in its collection. A module that fails partway through `register()` leaves nothing registered. A tool registered with `workflow=True` is also offered to workflow action steps as `oe__<name>` (see Workflows); `read_only=True` marks one that only reads. A step runs with nobody in the turn, so `offered` isn't asked: `extensions.in_workflow_step(name)` is True for that tool, during its call only, and the handler decides what an unattended call may do.\n\nDocuments come in the other way through `read_document` (`orchestrator.document_tools`): it reads a PDF, Word, Excel, CSV, Markdown or text file by `path` — one another tool saved, such as a Gmail attachment (`get_gmail_attachment_content`) or a Drive file (`get_drive_file_download_url`) — or a company document by `filename`, with an optional PDF `pages` range. A scanned PDF is converted (`knowledge.pdf_reader`: local OCR by default; with `PDF_PROVIDER_READING=true`, the deployment's own model through its provider's PDF support, falling back to local OCR) rather than returned empty. Reads are confined to the tool download folders — the same resolve-then-contain check as `oe__read_file` — plus the company docs folder, and it is withheld on turns private to the principal (`PRIVATE_TURN_WITHHELD_TOOLS`): those come from a contact's email, whose own attachments the poller has already read into the turn, and must not steer the Executive into company documents.\n\nThe Executive also backs the **Ask OE** panel's form-fill tier via `orchestrator.form_tools.propose_form_values`: when a chat turn arrives with a `<page_context>` block describing a form on the user's screen, the Executive can propose values for it. The proposal is delivered to the UI as a `form_patch` SSE event and placed into the form as highlighted suggestions — the tool never saves or submits anything; the user reviews and saves manually. The tool is **always** in the tool list (tool definitions sit at the top of the cached prompt prefix, so a conditionally-present tool would invalidate the prompt cache whenever panel and non-panel turns alternate); its description restricts usage to turns that carry a form descriptor. For questions about the product itself, the always-offered `read_user_guide` tool (`orchestrator/guide_tools.py`) returns any `guide/prebuilt/<id>.json` section; its description lists the section ids, fixed at import, so it never changes the cached tools prefix.\n\n**Take the lead** (`orchestrator.take_the_lead`) is how the Executive acts on its own, behind one gate. It has two switches, both off until someone turns them on. **As the Executive** is the principal's alone (`PUT /take-the-lead`). With it on, the unattended passes (reflection, research, the scheduler's proactive trigger) keep the acting tools solo mode otherwise withholds from them: booking, starting workflows, and messaging teammates rather than only the principal. `schedule_tools.unattended_toolkit` and the chat loop's unattended path then wrap every acting tool (`ACTING_TOOLS`, plus any MCP tool whose name sends, creates, updates, deletes or shares) in `gated_handlers` / `gated_call_tool`. The principal-only tools (`UNATTENDED_WITHHELD_TOOLS`) stay withheld, and every guard inside a handler still applies, including department approval levels (a booking in a department on Proposes is still a proposal) and the contact-egress rule. New mail or chat (any turn with an `origin_channel`) wakes the existing reflection early (`take_the_lead.wake`): one run waiting at most, five minutes after the first message and no more than every 30 minutes, as a one-off `take_the_lead_wake` scheduled action. Pause holds it like any scheduled work. **As you** is the Handle it for me dial's top step (delegation section).\n\n**The gate** is plain code (`take_the_lead.check`). Six kinds of action wait for a yes first, each with an Ask first switch, all on to start. The switch is the decision ledger's own mode for the class `take_the_lead_action:<kind>` (`propose` asks first, the default; `auto_execute` doesn't). The kinds are money, contracts and legal, hiring and people decisions, deleting/cancelling/sharing, someone new (an address on neither the roster nor the contacts) and big sends (a broadcast or department message, or more than five people). On top of these, the company (set by the principal) and each person (for their own As you) add structured rules: a person or address, a domain, words, or an amount at or above a figure. Added rules always hold, and an error reading them holds the action. The one thing the gate lets straight through is a direct message (`message_person` or a Slack, Telegram or Discord DM) whose only recipient is the principal (`_only_to_principal`): they are who it would wait for, so a card would only ask them to approve a message to themselves. Anything that reaches or acts on anyone else is checked, and a roster that can't be read is not the principal. A held action becomes a `take_the_lead_action` decision instance with a companion `DECISION_ALERT_SOURCE` card on Today, routed to the first teammate holding one of its People approval ranges (`take_the_lead.approval_ranges`, plain code, closest fit first: money to `spend_lt_2k`, `spend_lt_10k` or `spend_gt_10k` by its largest amount, with a higher range able to approve a lower one and no amount read as large, or to `customer_credit` for credit and payment terms; vendor contracts to `vendor_onboarding` then `legal_sign`, other contracts to `legal_sign`; hiring to `hiring_signoff`; anything else about the board or investors to `board_comms`; in Personal as in team mode), or else the principal through the authority gate's fallback (`departments.authority._route_proposal`). Deletes and shares always go to the principal. Only the principal and that approver see or resolve it (`DecisionClassSpec.principal_and_approver`). Approving it claims the row and carries out the exact call once (`take_the_lead.carry_out`: the unwrapped handler, or the gateway's `call_tool`, on an unattended session, with contact egress only when the principal approves). Declining drops it. Everything done or held is a row in `take_the_lead_log`. What it did and what was approved show in Recent activity (`today._build_activity`, kind `took_the_lead`), named but never quoted, since that feed is the team's. The held card's own `decision_resolved` row is left out because its payload quotes the message. `GET /today/activity` also adds the caller's own Handle it sends (kind `sent_as_you`, actor `you`), which are never in the shared feed.\n\n**In training.** The As the Executive switch has three positions: Off, **In training** and On (`take_the_lead.training`). In training, an action the gate would let through still waits, as a `training` hold for the principal alone, unless the principal has allowed that action with that person or thing (`take_the_lead.allowance`: \"Message Priya Nair\" covers a message to her on any channel; \"Book meetings with Priya Nair and Sam Lee\" meetings with exactly them; a workflow by id; a connected tool by name and the file it names, never one that reaches people such as a mail send or a share). The card carries Approve, **Approve + allow**, **Edit** (the message, a meeting's title, times or description, a task and its due date: `take_the_lead.apply_edits`) and Decline. Allowing is the principal's alone and needs a request the API can tie to them, as turning it on does; the six kinds and the added rules hold whatever is allowed. An edit approved with \"Do it like this next time\" is kept as an example (only the edited text, the principal's own words), and `take_the_lead.learned_note` hands the examples and the fact it's in training to the reflection and research passes in their user turn. After `SUGGEST_AFTER` (3) unchanged approvals of the same action in 30 days, Settings suggests allowing it. What it's learned is one list keyed by feature (`take_the_lead_allowed.feature`), so other features that learn from approvals can join it; each keeps its own switch. Act as me is the second (`act_as_me`, per person, `delegation.training`), with a training switch per setting (Replies, Follow-ups, Suggested actions, Drafts): its rows carry the person's id and the setting in their key, are listed and removed by that person alone, count toward their own cap, and never reach `learned_note`.\n\n**AI disclosure.** Nothing the Executive sends to people outside the web chat goes without saying it is an AI: plain code adds the line in the MCP gateway (mail) and at each chat send (Slack, Telegram, Discord, Google Chat replies, its DMs and room posts), never the prompt, so the persona and the cached system blocks are unchanged and a reply the model writes can't drop it. Replies the inbox watcher writes as a person carry their own line by that person's switches. See Integrations → **AI disclosure** and Act as me → **AI line on replies**.\n",+ "markdown": "The Executive (`openexecutive.orchestrator.executive.Executive`) is a single coherent persona that fans out to specialist sub-agents via Anthropic tool use. Each specialist subclasses `openexecutive.agents.base.BaseAgent`, carrying a `name`, `domain`, and `model`, and exposes `analyze(...)`, which wraps the question in user-turn context and calls Claude through the per-call provider. That context is per call and never cached: `<company_stage>` (the stage from the company profile — specialists never see the profile itself), in solo mode `<principal_role>` (what kind of principal the advice is for, in plain words, with their title and remit — `router.principal_role_context`), `<department_memory>`, `<past_decisions>`, `<failure_cases>` (the shipped case studies, and under them the workspace's own lessons that match the call, `memory/lessons.py`), `<relevant_knowledge>` and `<conversation_context>`, outermost first. The specialist's own system prompt is a static domain constant under one `cache_control` block, so it stays byte-identical across companies and profile edits. A chat turn takes the stage from its session's profile (the one the Executive reasons over, and the one an eval scenario injects); workflow steps and the MCP server's `consult_specialist` read it fresh from the profile on disk. The role tag follows the turn's mode: a chat turn pins the role on its session with the mode (`pin_turn_principal_role`: the session's `principal_role` override, else the workspace settings) and sends it in solo and nothing in team, so the org block, every specialist in the turn and any workflow the turn starts see the same role; callers with no chat turn read it fresh (`load_principal_role`: the current session's mode and role, else the workspace's), and a failed read sends no tag rather than failing the consult. The CFO, CSO and sales prompts key their advice on it: for a bootstrapped, self-funded or solo company they drop venture fundraising benchmarks and work from cash, and raise only if the founder wants to.\n\nRouting uses one `consult_specialist` tool. When to call it is spelled out in the persona's Domain Expertise section (\"Going deeper\") and in the tool's own description: any question that asks for judgment in a specialist's area (a decision, plan, analysis, negotiation, hire, contract term, pricing or fundraising move, board message, or a department's own targets and stance, since the specialist holds that department's memory) is consulted before the answer, several at once across areas; lookups in mail, calendar or documents, scheduling, status checks, routine drafting and questions about how the Executive works are answered without one. Chat eval scenarios hold this: `required_routing` names specialists the turn must consult and `no_routing: true` says it must consult none, and the runner fails a scenario that misses either (`evals.scenarios.routing_check`). Beside it the Executive carries two skill tools, `search_skills` and `load_skill` (skills are shown to users as **playbooks**, and every playbook belongs to a workflow: one that follows it, or its own Quick workflow). Chat finds and reads playbooks but never creates or changes one: work worth repeating is offered as a workflow through `draft_workflow`, with the method written into its steps, because workflows read playbooks at run time (approved scheduled ones included) and this loop also runs on inbound email and chat, so only a person can change what a workflow follows. A hidden built-in is invisible to search and load; each `search_skills` hit lists the `workflows` that follow it, Quick ones included, and the persona routes \"the finished deliverable\" to that workflow and quick or partial asks to the playbook inline; Tool calls made while proactive work is tagged (scheduler dispatch, reflection, research, alert review) feed the Attunement outcome ledger. Goals have three tools: `list_department_goals`, `update_department_goal` (progress the user reports) and `create_goal` (a new goal the principal states, filed under an area by slug or title and creating the area when none matches — see Org). `create_goal` runs only for the principal on a verified surface, and no unattended run is offered it: the tools in `schedule_tools.UNATTENDED_WITHHELD_TOOLS` are dropped from reflection's and research's toolkits by `unattended_toolkit`, and from the chat loop when its Session is marked `unattended` — the scheduler's PROACTIVE TRIGGER run, whose prompt quotes stored intent text; a call the model emits anyway gets an error tool_result. `record_decision_outcome` records how a past decision turned out — the weekly review lists decisions older than 30 days with no outcome as `[decision N]` — writing `decisions.outcome` (`episodic.update_decision`) and auditing the rationale; it has `create_goal`'s gate (the principal on a verified surface only; everyone else gets an audited refusal) and is in `UNATTENDED_WITHHELD_TOOLS` too. A missing or unknown id returns the decisions still waiting on an outcome, so the model can retry with the right one. Its schema is static; the solo persona has one line on it, and team mode learns it from the tool description, so the team persona is byte-identical. Attunement adds `list_open_loops` (what a person owes — everyone's for the principal only in a private conversation, otherwise the caller's own) and `close_open_loop`, which only closes a loop when the turn's resolved speaker is the principal or the loop's owner — an unrostered sender, a signed-in web user not on the roster, and unattended sessions are refused. `assign_open_loop` opens one on request (\"ask Ben to send me the Q3 numbers by Friday\") for the principal or a rostered teammate on a verified surface — never an email, a turn private to the principal or an unattended run, which are also withheld the tool — and only when `task` appears verbatim in what the speaker typed this turn, at most 5 per turn; that turn's extraction pass then opens no second loop for the same owner. The owner is told once on their own channel when someone else assigns it, and the result's `notified` says how that went, so the Executive reports it rather than messaging them as well. The roster write tools (`upsert_person`, `archive_person`, `set_department_head`) are the principal's alone, and only on a surface that verified the speaker — the web chat, the principal's own Slack or Discord, a channel whose adapter verified the sender itself (`Session.speaker_verified`, with the `caller_person_id` it resolved, never on a turn an email started), or a private Telegram chat when `TELEGRAM_WEBHOOK_SECRET` is set to a value Telegram can send (Telegram identifies the chat rather than the sender, and without that secret its webhook accepts anyone's update). A teammate, an email (even from the principal's address), Google Chat, the CLI, the MCP server and unattended runs get `status: refused` (audited, and no action chip), because a team member's People row is also the web sign-in and outbound-email allow-list. `upsert_person` takes `kind` (`team` / `contact`; a new person defaults to `contact` in solo mode, an update keeps the current kind) and `email_aliases` (other addresses the person writes from — the full list, replacing the current one; they match mail and may be emailed but never sign in, and one already on someone else is refused), and after every write any pending roster request whose sender now matches someone is closed and its held messages replayed. `resolve_roster_request` answers a **roster request** — someone not on the People list who wrote in and is waiting (see Org): `approve` (a new person; `kind` defaults to team for a company-domain sender, else contact, when the principal did not say), `link` (someone already listed, by `person_id`; `replace_channel_id` only when the principal said so) or `decline`. It has the roster tools' gate (the principal on a verified surface; audited refusal otherwise), is in `UNATTENDED_WITHHELD_TOOLS`, and answers only an id in `Session.trusted_roster_request_ids` — the ids the server printed that turn in a `<roster_requests>` block (`briefing.context.format_roster_requests_for_prompt`, up to 10 pending requests), which `render_and_trust` appends to the `<briefing>` digest on the principal's own verified turn only and records on the session in the same step, so an id the model invents or reads out of a message adds nobody. Each line is server-derived — id, channel, address or account id, the sender's name sanitised and marked unverified, a company-domain hint, the message count — and never what they wrote. The block rides in the **user turn**, like the digest, so the cached system blocks are unchanged; the tool definition is static, and the new tool only extends the sorted tool list. The web chat route resets the trusted set every turn, and a resolved id is removed from it. and `list_people` returns both kinds with `kind` — contacts only on the principal's own verified turn (they are private to the principal; anyone else gets the team as if no contact existed) — while `lookup_person` searches the team only. `ask_about_person` reads a person's peer memory fully only on their own verified turn; anyone else's answers only to a verified principal or teammate, and only when that person turned on \"Share my work style with the team\", framed to how they work and never their view of a colleague, and otherwise returns the same \"hasn't chosen to share\" result whether or not anything is known. A teammate's own mail with the Executive is theirs the same way: every mailbox call the model makes through the MCP gateway (Gmail or Outlook, by `call_tool`, from a script, or a workflow step run from chat) passes through `orchestrator.teammate_mail`. A search excludes every other teammate's address server-side, except on mail the reader is also on, and is filtered again entry by entry; any other call that names a message or thread (read, attachment, reply, forward, label) must use an id a filtered search returned to the same reader in this conversation (`Session.mail_ids_seen`) or the inbound email the turn answers; reads are filtered message by message, so a message naming another teammate is left out unless the reader is in its From / To / Cc; a reply that would quote such a thread, or an Outlook forward, reply or attachment read of such a message, is refused; and a conversation in which a teammate other than the principal was shown their own mail becomes theirs alone, as Act as me's do. Outside mail and the reader's own are untouched; an email turn reads as its sender only when Gmail authenticated it, and any other unverified reader sees no teammate's mail, a background run the model drives reads as the principal and a workflow step outside any session as nobody, an Outlook inbox rule that forwards or names another teammate is refused, and the poller and the brief, which read the mailbox themselves, are unaffected. Their own chats are theirs too: every audit row of a teammate's verified turn is theirs (`people_tools.teammate_turn_owner`, see Audit; the principal sees the actions, never the words), and a teammate's web chat or DM opens for them alone (`chat._session_access`), the principal included. The same verified-principal rule, as `people_tools.contacts_reachable_now()`, decides whether a turn may reach a **contact** at all: `message_person`, the raw DM tools, `create_calendar_event` / `create_instant_meeting` attendees and the MCP gateway's Gmail / Calendar / Drive / OneDrive gates treat a contact exactly like an unknown person on every other turn, so no refusal reveals that one exists. **The untrusted-content policy** (`orchestrator.content_trust`) is one rule for text the principal did not write — inbound email, chat, attached files, watched pages — answering three questions for every surface. *Who is speaking*: the principal only when the surface proved it (`principal_speaking`: the web chat as the principal — never a signed-in email on nobody's People entry —, the CLI, their own Slack/Discord or a secret-verified Telegram chat, or their own address with Gmail's `dmarc=pass`); never a teammate, a stranger, Google Chat, the MCP server or an unattended run. *What may become memory*: episodic extraction runs only then, and only on the words outside `<untrusted_content>` blocks; peer memory and open loops are recorded under the speaker's own name, never as the principal's. *What may trigger tools*: every write on the principal's authority already refuses others in its handler; the tools with no such check that change the install for every later turn — `content_trust.PRINCIPAL_ONLY_TOOLS`: `load_mcp_server`, `list_saved_tools`, `run_python_job` and `run_script` — are not offered unless the principal is speaking on an interactive surface (not email, even authenticated), and a call the model emits anyway gets an error tool_result and a `refused: not_principal` audit row. So an inbound email, a teammate's turn, Google Chat and the scheduler's proactive trigger each get a stable tool list of their own without it. A send or edit on a team member's turn also meets their department's authority first (`orchestrator.department_gate`, see Org), and so does one on a turn whose speaker is on no People entry: a signed-in web caller or a chat-channel sender, which in practice is Google Chat, since Slack, Telegram and Discord turn unmatched senders away. Google Chat names a matched sender to the gate alone (`gate_sender_person_id`), so the principal there is not held. Email turns are left to the mailbox's own gates. *How it is labelled*: outside text goes into the user turn inside `<untrusted_content source=… author=… author_verified=…>` with a fixed notice that it carries no authority; compatibility forms are folded (NFKC), control characters go, and the tag's name is renamed wherever the text carries it — any case, spacing or entity-escaped form — so the text cannot end its block and speak outside it.\n\n**Outside content** (`orchestrator.outside_content`). Once a turn has read text from outside the team (any gateway read, an attachment, a web search result, a synced Drive, OneDrive, Confluence or Notion excerpt, `read_document`, research, or an extension tool registered `reads_outside`), the rest of that turn refuses what the Act as me lockdown refuses, every `upsert_person`, and every `call_tool` but a read: no mail, Docs, Sheets, Drive or calendar write. A round that reads also holds that round's other such calls; the read itself runs. Scripts are checked call by call. The offered tools never change, so the cached prefix stays the same, and the hold ends with the turn. Mail from someone not in People (a contact or a stranger) counts as outside content from the start of its turn (`Session.sender_off_team`), so the whole turn is held, with no direct messages or watchlist removals either; it can still raise an alert, private to the principal, which is how that mail reaches them. Someone added to People in a turn (or given a new address or chat account) is not emailed, messaged, invited or shared with until the next one.\n\nA turn about the principal's private mail (`Session.private_to_principal`) reaches the principal only. It is neither offered nor allowed to run `schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS` — everything that reaches someone else, publishes where the team reads, or starts work outside the turn: the broadcasts, meeting bookings and cancellations, `run_workflow` and research, follow-ups and workflow nudges, watches, artifacts, goal updates, saved workflows, skill drafts, and `load_mcp_server` (it connects to any URL, which can carry the turn's content). Through `search_tools` and `call_tool` it reaches only `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads (mail, calendar, and Drive, Docs and Sheets search and file reads, with their Microsoft 365 twins; OneDrive's `download-bytes` only for a file's content) and the Gmail send and draft the gateway narrows to the principal. A search shows it nothing else, and a call to anything else (Google Chat, a Docs or Drive write, `manage_event`, another server) is refused (`schedule_tools.private_turn_withholds`). A call the model emits anyway, MCP tools included, gets an error tool_result and writes an audit row, and every audit row the turn writes is the principal's alone.\n\nA turn another AI app asks over the MCP server (`Session.from_mcp_client`, set by `ask_executive`) reads and advises but never acts, unless the request may act (below). It is neither offered nor allowed to run `schedule_tools.MCP_CLIENT_WITHHELD_TOOLS`: the private-turn and unattended sets, plus every direct message (`message_person`, the Slack, Discord and Telegram DMs), alert acks and new alerts, brief edits, closing open loops, roster and department-head writes, watchlist changes, workflow drafts and form proposals. It gets no Act as me, `recall_history` or extension tools, and of the gateway tools only `schedule_tools.MCP_CLIENT_MCP_TOOLS`: the private-turn reads without the Gmail and Outlook send and draft tools. The set is fixed, so the variant keeps a stable cached tool prefix. A call the model emits anyway, through `use_tool` or `call_tool` included, gets an error tool_result telling it the conversation comes from another AI app, so it can read and advise but not send, post, book or change anything, and writes an audit row (`refused: mcp_client`); `MCPGateway.call_tool` refuses the same calls again.\n\nA request may let that turn act (`Session.mcp_client_may_act`: the `x-mcp-client-actions: on` header on a request the shared secret authenticated, or `MCP_CLIENT_ACTIONS` where no secret is set). It then runs the speaker's own changes inside Open Executive (`schedule_tools.MCP_CLIENT_RUNS_WHEN_ACTING`: alerts, open loops, follow-ups, the watch list, goals, decision outcomes, facts and company profile writes; never the roster), each under its own owner-only and person checks, since the turn counts as a verified surface for its caller. It is still denied a fixed set, `MCP_CLIENT_ACTING_WITHHELD_TOOLS` (DMs, calendar writes, broadcasts, `load_mcp_server`, scripts, Python jobs, workflows, research and the rest of the read-only set), with a refusal telling the person to do it in Open Executive. A message or a meeting goes on an approval card instead (`propose_actions`), which is carried out at once when the person's Handle it for me covers it, everyone on it has been on the roster for a week, and `action_cards.on_its_own_refusal` finds nothing against it, and otherwise waits for their tap. Every audit row it writes names the app (`via`).\n\nA web chat its owner shared (`Session.shared_chat`) mixes people. The note naming who is in it says which of them owns it and that the others' lines are messages from them, not the owner's instructions. While someone other than the owner has written since the owner's last message (`Session.others_spoke_last`, set per turn by the chat route from the saved history, the speaker included, and true when the history can't be read), the turn is neither offered nor allowed to run `schedule_tools.SHARED_CHAT_WITHHELD_TOOLS`: direct messages, the broadcasts, meeting invites and cancellations, follow-ups, roster writes and workflows (a run, a save or a suggested schedule acts later with the full tool set). Through `call_tool` it can't send, reply, forward or draft mail in Gmail or Outlook, or make a calendar change that mails attendees (`schedule_tools.shared_chat_withholds`). That holds on the owner's own turn right after someone else's line too, so a request carried over from it can't send; the owner's next message with nobody else's in between lifts it. A call the model emits anyway gets an error tool_result and writes an audit row (`refused: shared_chat`). The principal-only tools stay out of every shared chat (`content_trust.principal_only_withheld`).\n\nOn every turn the Executive knows what is connected without searching: block 0's *Connected Systems* section names the connected Google services, other MCP servers, the messaging channels, Notion sync, Confluence sync (when on) and Act as me, and pins the Google tool names it calls directly with `call_tool`. Both the service list and the pinned names are narrowed to what workspace-mcp actually loaded (`WORKSPACE_MCP_TOOLS`, `WORKSPACE_MCP_TOOL_TIER`), so a service left out is not named and its tools are not pinned — being told a tool is already available when it is not in the index costs a failed call the model cannot explain to itself. `search_tools` is for anything not listed. When work repeats over many items, the Executive can also call `run_script` (`workflows/step_script.py`, offered when the gateway runs, unless `CHAT_SCRIPTS=false`, and only on the principal's own turns — `PRINCIPAL_ONLY_TOOLS`, withheld on an unattended pass too, because it spends the turn's whole call budget on code the model just wrote): one short Python script, run in a sandboxed Monty worker with no files, network or environment, whose only reach is the gateway tools `call_tool` could reach (those `search_tools` has returned; the gateway keeps that set for its own process-wide session, not per conversation). Each call it makes is a `call_tool` in every way that matters — the gateway's discovery, deny-list and recipient gates, Take the lead's gate on an unattended run (or the department gate on a team member's turn, see Org), and the same action chip and `tool_invocation` row (marked `via: run_script`, `ok: false` when it raised), as each call happens; the script itself gets a `kind: script` row with its source and result. Its wall clock is half the turn's deadline, so a long script ends with the list of calls it made rather than being cut off with the turn, and a stopped turn closes it and its worker. A turn private to the principal is not offered it, and the Act as me lockdown withholds it whole. Besides gateway tools, a chat script may call a fixed list of the Executive's own tools (`step_script.CHAT_OWN_TOOLS`: reads, alerts, open loops, goals, the watch list, follow-ups, `message_person`, `upsert_person` — nothing that broadcasts, books calendars, edits memory or skills, or starts workflows or research), each only when the turn is offered it and through the turn's own handler (Take the lead's gate included), with the same chip and a `kind: skill`, `via: run_script` audit row. A direct call needs a `tool_use` each, so a turn's scripts share a budget instead: `CHAT_SCRIPT_MAX_CALLS` (default 200) calls in all, and per-turn caps on own tools that could otherwise act in bulk (`CHAT_OWN_TOOL_CAPS`: `message_person` 10 — messaging the whole roster would be a broadcast — `upsert_person` 25, `create_alert` 50); a refused call tells the model to say what is left. A call stopped mid-flight by the script's clock or the turn still gets a `cancelled` audit row, since it may have run. Because every round re-reads the conversation, the loop also nudges at the moment of choice: after a round whose results include a list of five or more items (`step_script.lists_many`), with `run_script` on offer and not used that round, it adds the constant `FANOUT_HINT` as a text block in that round's user message (never a cached block), once a turn, pointing the per-item work at one built tool. For library work on files (PDFs, spreadsheets, charts, images) the chat also has `run_python_job` (see Workflows → Python jobs): Python with a fixed library set in a Deno-isolated WebAssembly sandbox, fed Knowledge files by name, the message's own attachments as sent, or text it already holds, and able to keep a job that worked as a Custom tool, with result files linked for the principal to download; it is offered only on the principal's own turns and only where the sandbox is installed (not offered otherwise, so the tool prefix stays fixed per process). Agent Activity shows each run as one \"Built tool\" card (debug event `script_run`: ok, the calls it made, how many, how long, and the kept or reused tool's name). The persona's tool-building section is present only when chat scripts can actually run (the setting and Monty installed). `TOOL_BUILDING_ADDENDUM` in the cached persona tells the Executive when to build a tool — a job that looks something up and then checks or acts on each result, paged results, more than about ten items, or an answer that needs three or more reads (find, open, read; the tool returns only what answers the question, not whole documents, and only what is about to be edited or quoted at length is read in full), while a handful of items already named go as direct calls in one turn — and never to say it has none, and to talk about it as building a tool or doing it in one go. On the principal's own verified, interactive turns, a script that works can be saved as a named tool (`save_as`; elsewhere the script runs but is not saved) and run again with `run_script(tool=…, inputs=…)`; `list_saved_tools` (a constant definition, in `PRINCIPAL_ONLY_TOOLS` with `load_mcp_server`, so offered only while the principal is speaking on a verified, interactive surface; `run_script(tool=…)` is refused on any other turn) lists them, and each call a saved tool makes is a gateway call like any other (see Workflows → Saved tools). The tool's definition is a constant, so the cached tool prefix does not move. Multiple parallel `tool_use` blocks in a single assistant turn fan out concurrently through `router.route_parallel`, each running its own domain-filtered ChromaDB query (3 built-in and 2 company chunks by default, see the RAG section) before the specialist sees the question. The fan-out is failure-isolated per call: a specialist that raises or returns no text becomes an `UNAVAILABLE` tool_result (`router.specialist_unavailable_result`) instead of failing the whole turn, and its area — \"finance\", \"legal\", never the specialist's name — is reported to the user under the web reply, or by the Executive in its reply on other channels, unless another call to it answered that turn. A failed specialist does not count as consulted, so it takes no committee seat. Cancellation (Stop) still propagates. The Executive then synthesizes the returned analyses into one reply.\n\n`remember_fact`, `forget_fact` and `update_company_profile` (`orchestrator/fact_tools.py`) make a correction stick: the first two keep or retire a standing fact in `memory.facts`, and the third changes one field of the company profile. They share `record_decision_outcome`'s gate (the principal on a verified surface, an audited refusal for everyone else) and are in `UNATTENDED_WITHHELD_TOOLS`. `remember_fact` alone also admits a rostered teammate on a verified surface (web signed in, their own Slack or Discord): the fact is stored attributed (`recorded_by_role=\"teammate\"`, rendered `(per <name>)`), and is held as a `proposed` row (`awaiting_approval`) until the principal approves it, unless the principal marked that teammate trusted (\"needs my approval\" off; on by default) — and even then when it would replace the principal's fact. All three are also in `PRIVATE_TURN_WITHHELD_TOOLS`, since what they write or retire is read on everyone's turns. On the principal's own authenticated email (primary address, with Gmail's own `Authentication-Results` reporting `dmarc=pass`, not forwarded) the three tools check the request as usual, then hold it as `awaiting_confirmation`. It applies only when the principal replies to a one-time token emailed to their own address (`integrations.fact_confirmation`); the split into a check step and an `apply_*` step lets chat and the confirmed reply share one apply path. Each write also needs a `source_quote` found in the speaker's own words this turn. The active facts reach every specialist as a `<standing_facts>` user-turn tag: `route_to_specialist` reads them (None → the store, \"\" → none) for chat consults and workflow steps alike, and `BaseAgent.analyze` places the tag next to `<past_decisions>`, never in the cached specialist system prompt.\n\nThe ten entries in `SPECIALIST_REGISTRY` (`openexecutive.orchestrator.router`):\n\n| Key | Agent | Domain |\n| --- | --- | --- |\n| `cso` | `StrategyAgent` | strategy |\n| `cfo` | `FinanceAgent` | finance |\n| `chro` | `HRAgent` | hr |\n| `gc` | `LegalAgent` | legal |\n| `coo` | `OperationsAgent` | operations |\n| `cmo` | `MarketingAgent` | marketing |\n| `cpo` | `ProductAgent` | product |\n| `sales` | `SalesAgent` | sales |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5-5`; the deep-reasoning tier (CSO, CFO, GC, Board) runs on `DEEP_REASONING_MODEL`, `claude-sonnet-5-5` by default, with adaptive thinking; routing/fast classification uses `claude-haiku-5-5`. Requests are fitted to the model's generation on the way out (`feature_gate.fit_claude_generation`): 5-generation Claude models never receive `temperature` / `top_p` / `top_k`, and Haiku 5.5, which thinks unless told otherwise, gets thinking turned off when the caller asked for none. The Council's **Deep reasoning** toggle is honoured on Claude Opus/Sonnet (direct or via OpenRouter) and on any OpenRouter model whose live catalog entry supports `reasoning` (today all OpenAI, Gemini, DeepSeek and Grok entries; not Llama) — the request translator turns Anthropic adaptive thinking + effort into OpenRouter's `reasoning` parameter. It is a silent no-op on models that can't reason, and disabled for Haiku, which rejects adaptive thinking. A PDF `document` block is translated too: it becomes an OpenAI `file` part, and OpenRouter requests carrying one add the `file-parser` plugin (`native` for models whose catalog entry lists `file` input, else `PDF_OPENROUTER_ENGINE`, default `mistral-ocr`). `FeatureSpec.supports_pdf_input` gates it per model — off for a local server unless `LOCAL_PDF_INPUT` — and a gated-off PDF becomes a text note rather than vanishing. The Council picks a model in two steps: a **Provider** dropdown (Anthropic, OpenAI, Google, Meta, DeepSeek, xAI, Local, …), then a **Model** dropdown limited to that provider, with readable names (\"Claude Opus 5.5\") and the raw id and serving route shown underneath. The Anthropic group combines the direct Claude models (`claude-fable-5-1`, `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5-5`, `claude-sonnet-5`, `claude-haiku-5-5`, `claude-haiku-4-5`) with any Claude generation that exists only on OpenRouter, and never lists a model twice. With `OPENROUTER_ENABLED`, the non-Anthropic entries come from OpenRouter's live `/models` catalog (fetched at startup, refreshed in the background, filtered to tool-capable paid text models from an allowlisted vendor set), falling back to a built-in snapshot if the fetch fails. Every Council agent also takes **additional instructions** (`agent_overrides.instructions`): text appended after its prompt by `agents.overrides.append_instructions` inside an `<additional_instructions>` block. `BaseAgent.base_system_prompt()` is the built-in prompt or its full replacement (what the Council's editor shows); `effective_system_prompt()` is that plus the instructions (what every call sends), and the Executive gets the same text through `build_system_blocks(persona_instructions=…)`. Unlike a replaced prompt, instructions leave the agent on its built-in prompt, so prompt improvements keep reaching it. A **Quality** choice above the agents (`agents.presets`) sets every agent's model and deep reasoning at once: **Fast** puts every agent on a small model (`claude-haiku-5-5`, else `claude-haiku-4-5`) with deep reasoning off, **Balanced** returns each agent to its built-in defaults, and **Thorough** puts the Executive and the domain specialists on the largest allowed model (`claude-opus-5-5`, else `claude-opus-5`) with deep reasoning on where the model supports it, leaving triage and the helpers below on their defaults. Presets change quality only; they never cap spend. Each preset resolves against the install's model allowlist at request time and is offered only when one of its models is allowed. Applying one writes ordinary per-agent overrides (model and deep reasoning only), so history, rollback and later per-agent edits keep working; an agent changed on its own afterwards shows as **Custom**. Each Council agent has a **visibility**: `core` for the Executive and the domain specialists (`BaseAgent.visibility = \"core\"`, which a new specialist must declare) and `internal` (the default) for triage and the helper agents below. Thorough moves only core agents. The Council opens in a **simple view**: the Quality choice, the voice picker, and only the core agents, each with its additional instructions and a model badge. **Show all agents** lists the internal ones too, and **Advanced** opens the full page (the browser remembers the choice). Eight Council-only agents are model/prompt-overridable in the UI but NOT callable via `consult_specialist`, because they are deliberately kept out of `SPECIALIST_REGISTRY`: `quality_judge` (committee review), `utility_fast` (gates, titles, decision parsing), `research` (the `executive_research` fan-out), `fixture_generator` (invents demo companies), `engagement_intake` (models a real client from intake material), `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments), `workflow_designer` (runs the conversational New workflow wizard on `/jobs/new`: searches the available tools, asks clarifying questions, then drafts a validated dynamic-workflow definition for the user to review), and `workflow_actor` (runs a workflow's `action` steps: a bounded tool-use loop limited to the tools the user approved for that step). `fixture_generator`, `engagement_intake` and `onboarding_interviewer` share one shape — a forced tool call producing a whole company, validated for referential integrity, with a single repair retry — but opposite epistemics: the fixture author invents, the other two extract and leave unstated facts empty rather than guessing. When the workspace is in solo mode, `onboarding_interviewer`'s first user turn is prefixed with a short hint (`interview.solo_hint(role_kind)`, one static constant per role kind from the onboarding role step): the draft names only the principal, as principal, and no departments; an owner is asked about the offer, customers, pricing, cash and runway, an in-house executive about their organisation (drafted as the company — their employer), function, remit, manager, team size as context and what they are measured on, an independent about their practice, clients and pricing, and with no role given the role-neutral `SOLO_HINT` asks which they are. The hint rides in the user turn and the tool array is unchanged, so the cached system prompt and tool prefix are the same in both modes.\n\n**Voice.** The Executive answers in one voice persona, substituted into block 0 at `{VOICE_PERSONA}` (`personas/loader.get_active_body`) from the Executive override's `voice_persona_slug`. Three general voices ship in `personas/builtin/`: **Direct** (`default`, the slug used when none is set: answer first, brief and decisive), **Supportive** (a warm coach who explains the why and checks how the plan sits) and **Analytical** (numbers first, options and trade-offs, then one recommendation). They are offered by a shared picker in setup (`/onboard`, after the workspace choice) and in Settings → Executive, which saves through `PATCH /agents/executive`; a built-in voice's frontmatter carries the picker's one-line `description` and `sample` reply. The named-executive voices are marked `legacy: true`: the picker hides them, but they still load, so an install that picked one keeps it, and the Agent Council lists them under \"Legacy voices\". Voice files hold disposition only; the response-length ladder lives in `prompts/executive_persona.py`, and a test keeps numeric length rules out of every voice file. An eval scenario may set `voice_persona` to answer in a voice; it rides on `Session.voice_persona_slug`, which wins over the override for that session only.\n\nOne more structured-output utility agent sits beside `triage`: `openexecutive.agents.alert_review.AlertReviewAgent` (routing model, one forced `emit_alert_reviews` tool call, never raises). The alert review job hands it a batch of open alerts with evidence and gets back, per alert, a verdict (relevant / changed / resolved / stale), a confidence, the evidence it relied on, a one-line note, why-now, an optional deadline, and a recommended move (none / route / nudge / escalate / draft / suggest_workflow / merge / close) with its parameters. Like `triage`, it never mutates state — `alerts.review.apply_verdict` executes the verdicts deterministically within authority, so the model's job is judgment, not action.\n\n**Solo mode.** When the workspace (or the turn's session) is solo — one person using Open Executive for themselves — the Executive works for that one person, the principal, whatever their role: they may run their own business, lead a function inside a larger organisation, or work independently, and the persona reads which from the context instead of assuming it — the role lines under \"Your Principal\" in the org block, when the principal gave their role (workspace settings: kind, title, reports to, remit, measured on). Its persona swaps the team sections (\"You Are a Member of This Executive Team\", \"Choosing Who to Tell\", \"Departments & Org Coordination\") for \"You Work for One Person\", \"The People in Their World\", \"Who Hears From You\" and \"Goals and Areas\". Solo means only the principal uses Open Executive — not that they have no people: their manager, direct reports, peers, clients, investors and board are contacts. The Executive helps the principal work with them (a 1:1 or review prep, an update or budget case for their manager or board, a negotiation) but does not coordinate them, contacts them only when the principal asks and only if they are a contact, and never offers to loop the principal in. Every specialist stays relevant — HR for the principal's own reports, board and investor communications for reporting upward. Goals are grouped by *area* (the tools' `department_slug` is the area's slug). The chat loop withholds `send_department_message`, `send_company_broadcast` and `set_department_head` from its tool list, and a call to one of them anyway gets a JSON error tool_result instead of running. The mode is resolved once per turn and pinned on the session, so the persona, the org block, the tools and every tool handler agree — a switch made mid-turn applies from the next turn. Team mode is unchanged.\n\nEvery specialist *advises* — each returns domain analysis the Executive synthesizes into one voice. None of them act on the company's behalf; the side-effecting tools in the main loop (schedule, people, departments, broadcast, watchlist, workflows) belong to the Executive, not to a specialist.\n\n`recall_history` (Always in the loop, `orchestrator.history_tools`) reads the speaker's own notes, on the same terms as `ghostwrite_email` below: its own registry, offered only on a verified turn in a conversation private to them with their switch on; its `due` flag lists only dated notes, soonest first (see Memory). The ghostwriter below also gets the writer's notes from mail every recipient was on, as a consistency check (`<writer_noted>`).\n\nThe morning reflection, which has no question to look up and no specialist to consult, gets one more read-only tool of its own: `search_knowledge` (`orchestrator.knowledge_tools`), the same knowledge lookup a chat turn makes, for what the company's documents say about a customer, contract, price or policy before it acts.\n\nA fifth, `remind_me` (`orchestrator.reminder_tools`), sets a plain-text reminder sent to the speaker alone when it is due; it opens no mailbox, so it never locks a turn. A sixth, `propose_actions` (`orchestrator.action_card_tools`), does nothing itself: it leaves the speaker a card of up to five actions (a meeting, a message, a new contact) that happen only when they tap Approve, so it stays on after a turn read mail; it is where what an email itself asks for goes, since that is never done on the email's say-so. Four read-only tools beside it read the speaker's own mailbox on the same terms — `search_my_email`, `read_my_email`, `read_my_email_attachment`, `my_email_awaiting_reply` (`orchestrator.mail_read_tools`) — and `my_calendar` their own calendar while Read my calendar is on, capped per turn, other people's messages and attached files returned as untrusted blocks (see Act as me). Beside them, `save_my_email_attachment` copies one attached file, when the speaker asked in their own words, into a fixed folder of the Executive's own Drive or OneDrive and shares it with them alone, every call built in codeOne tool writes under someone else's name, and it is fenced in code rather than the prompt. `ghostwrite_email` (**Act as me**, `orchestrator.delegation_tools`) writes an email as the person the Executive is speaking with and saves it as a draft in their own mailbox, Gmail or Outlook (`delegation.gmail.gmail_for` picks the client by the person's credential); chat never sends it (the person sends it themselves, or taps Send on its card). It lives in its own registry, never `_ALL_SKILL_TOOLS`, so reflection, research and workflow toolkits can never carry it. The chat loop adds it only on a turn `delegation.settings.pin_turn_delegation` offered it to — the principal, or a team member once the owner lets them, with it on, verified, in a conversation private to them (the web chat, a Slack or Discord DM, a verified private Telegram chat), on an attended turn — and builds that turn's handler map from both registries, so on any other turn a call to it is an unknown tool. From the round that calls it until the turn ends, the dispatch guard refuses only what opens an outside address, runs a script or workflow, or posts to everyone (`delegation.lockdown`), without changing the offered list; messages and invites to the roster, follow-ups, facts in the person's own words and a contact they name still run, each fenced in its own path. A later turn in the conversation stays private to its owner but holds nothing: the person asking again, having read the reply, is their own request. A contact add the lockdown refuses becomes an approval card in the chat instead (`propose_actions`). Recipients are chosen in code, never by the model (a draft's new email may go to any address, named back to check when it is neither on the roster nor typed), and the text comes from the **ghostwriter** (`delegation.ghostwriter`), a tool-less call with a constant prompt plus the person's \"How I write\" profile. The ghostwriter is deliberately not a Council agent: the Council's edit routes have no principal check. See **Act as Me (Delegation)**. A second tool joins the same way: `recall_history` (`orchestrator.history_tools`, Always in the loop) reads the speaker's own notes of what they said, by email or in chat. It has its own registry and per-turn handler map too, and the loop adds it only when `history_tools.recall_person` finds the speaker verified, in a conversation private to them, on an interactive turn that isn't private to the principal, with their notes switch on. It doesn't need Act as me. After every chat turn the Executive also hands the speaker's own words to `history_chat.schedule_chat_notes`, which takes notes in the background when their switch is on and the surface verified them (see **Memory**). A meeting `create_calendar_event` proposes works the same way when the person chatting is the one who approves it: its chip carries the `decision_id` and the chat shows the meeting card (Approve, Edit, Dismiss) under the reply, while the briefing keeps it too. A tool result held for someone else's approval (`waiting_for_approval`, the department gate) gets a *Waiting for approval* chip, never a done one.\n\nThe Executive can also launch *any* workflow conversationally: `orchestrator.workflow_run_tools` adds `list_workflows` (the launchable catalog with each workflow's inputs) and `run_workflow` (runs a built-in or custom workflow to completion and returns its artifact, checkpointing approval gates as `awaiting_human`). `run_workflow` runs the weekly review, and in solo mode the morning brief, only for the principal on a verified surface (`Workflow.principal_only_modes`, `create_goal`'s rule); anyone else gets an audited refusal that does not name the rule. A run whose `result` event reports `private_to_principal` (the morning brief on the principal's own verified turn, when it read their private rows) still returns its artifact into that turn, but the stored run keeps `persistence.PRIVATE_RUN_ARTIFACT` instead of the text, since run history is readable by everyone signed in. This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nDeliverables are first-class too. `orchestrator.artifact_tools` gives the Executive three tools: `draft_artifact` publishes a memo, web page (`html`), Word document (`docx`), spreadsheet (`xlsx`, from structured `sheets`) or a `link` to something it created in one of the principal's connected apps through the generic MCP gateway (`search_tools` → `call_tool`, any server — no vendor is named), and returns the artifact's id and link; `list_artifacts` and `get_artifact` let it find and reread its own past work (drafts and workflow outputs alike, through the same `artifact_records` read model the API uses). Every artifact belongs to someone: a draft to the person whose turn published it (`artifact_records.current_viewer`; with nobody speaking, the scheduler or the CLI, the principal), and a run someone started by hand to them, while scheduled runs are the team's. The tools, the recall, `message_person`'s link and mail attachments only ever reach the speaker's own (a link is refused when the recipient couldn't open it), not even the principal sees a teammate's, and a speaker who isn't on the People list publishes nothing. A workflow's own session inside someone's turn (the research synthesis) is pinned to that turn's viewer (`Session.documents_viewer`). Revising is `draft_artifact(supersedes=<id>)`, which archives the earlier version. When the principal asks for a deliverable the tool is always used; the \"quiet is the right default\" bar applies only to unprompted drafts. The format enum is a hard-coded sorted tuple so the cached tool schema stays byte-stable. Delivery: `message_person(person_id, text, artifact_id?)` appends the artifact's title and a `UI_BASE_URL/artifacts/<id>` link (through the same outbound guard as any DM; the link needs Open Executive access), and a Gmail send/draft can attach the file itself by `artifact_id` — see Integrations.\n\n**Extensions** (`orchestrator.extensions`). An install can add chat tools and kinds of document without changing this code. `OPENEXECUTIVE_EXTENSIONS` names Python modules. The first turn, or the first Documents read, imports each one and calls its `register()`. A module that fails is logged and skipped. `register_tool` takes an `ExtraTool`: a definition, an async handler, an optional `tool_groups` group (new or existing) and an optional chip. It refuses a name the loop already knows (`executive.builtin_tool_names`). An extension tool is never in `_ALL_SKILL_TOOLS`, so reflection, research and the synthesis never see it. The chat loop adds it per turn, like the Act as me tools, but never on an unattended run, a turn private to the principal or to a speaker who isn't on the People list (mail from a stranger), and only where its own `offered(session)` says. That predicate depends only on the kind of turn, so each kind of turn keeps one cached tool list. Act as me's lockdown refuses it once the turn has read the owner's mail, because it is unclassified and the lockdown fails closed, unless it was registered with `after_mail_read=True`: a tool that only reads the install's own data and carries nothing the model wrote anywhere outside. Its chip goes through `action_chips.summarize_action`, which applies the same no-chip rules for an error or refusal and keeps a link to a path inside the app. `register_collection` adds a kind of document: a drafted artifact tagged `collection:<name>` carries that collection on its record. The Documents page gives each collection its own filter. The collection's `on_change` hears about archive, restore and delete before they happen; if it raises, the change does not happen. `draft_artifact(supersedes=…)` refuses a collection's document. The alert pipeline strips `collection:` tags, so only the extension's own code files a document in its collection. A module that fails partway through `register()` leaves nothing registered. A tool registered with `workflow=True` is also offered to workflow action steps as `oe__<name>` (see Workflows); `read_only=True` marks one that only reads. A step runs with nobody in the turn, so `offered` isn't asked: `extensions.in_workflow_step(name)` is True for that tool, during its call only, and the handler decides what an unattended call may do.\n\nDocuments come in the other way through `read_document` (`orchestrator.document_tools`): it reads a PDF, Word, Excel, CSV, Markdown or text file by `path` — one another tool saved, such as a Gmail attachment (`get_gmail_attachment_content`) or a Drive file (`get_drive_file_download_url`) — or a company document by `filename`, with an optional PDF `pages` range. A scanned PDF is converted (`knowledge.pdf_reader`: local OCR by default; with `PDF_PROVIDER_READING=true`, the deployment's own model through its provider's PDF support, falling back to local OCR) rather than returned empty. Reads are confined to the tool download folders — the same resolve-then-contain check as `oe__read_file` — plus the company docs folder, and it is withheld on turns private to the principal (`PRIVATE_TURN_WITHHELD_TOOLS`): those come from a contact's email, whose own attachments the poller has already read into the turn, and must not steer the Executive into company documents.\n\nThe Executive also backs the **Ask OE** panel's form-fill tier via `orchestrator.form_tools.propose_form_values`: when a chat turn arrives with a `<page_context>` block describing a form on the user's screen, the Executive can propose values for it. The proposal is delivered to the UI as a `form_patch` SSE event and placed into the form as highlighted suggestions — the tool never saves or submits anything; the user reviews and saves manually. The tool is **always** in the tool list (tool definitions sit at the top of the cached prompt prefix, so a conditionally-present tool would invalidate the prompt cache whenever panel and non-panel turns alternate); its description restricts usage to turns that carry a form descriptor. For questions about the product itself, the always-offered `read_user_guide` tool (`orchestrator/guide_tools.py`) returns any `guide/prebuilt/<id>.json` section; its description lists the section ids, fixed at import, so it never changes the cached tools prefix.\n\n**Take the lead** (`orchestrator.take_the_lead`) is how the Executive acts on its own, behind one gate. It has two switches, both off until someone turns them on. **As the Executive** is the principal's alone (`PUT /take-the-lead`). With it on, the unattended passes (reflection, research, the scheduler's proactive trigger) keep the acting tools solo mode otherwise withholds from them: booking, starting workflows, and messaging teammates rather than only the principal. `schedule_tools.unattended_toolkit` and the chat loop's unattended path then wrap every acting tool (`ACTING_TOOLS`, plus any MCP tool whose name sends, creates, updates, deletes or shares) in `gated_handlers` / `gated_call_tool`. The principal-only tools (`UNATTENDED_WITHHELD_TOOLS`) stay withheld, and every guard inside a handler still applies, including department approval levels (a booking in a department on Proposes is still a proposal) and the contact-egress rule. New mail or chat (any turn with an `origin_channel`) wakes the existing reflection early (`take_the_lead.wake`): one run waiting at most, five minutes after the first message and no more than every 30 minutes, as a one-off `take_the_lead_wake` scheduled action. Pause holds it like any scheduled work. **As you** is the Handle it for me dial's top step (delegation section).\n\n**The gate** is plain code (`take_the_lead.check`). Six kinds of action wait for a yes first, each with an Ask first switch, all on to start. The switch is the decision ledger's own mode for the class `take_the_lead_action:<kind>` (`propose` asks first, the default; `auto_execute` doesn't). The kinds are money, contracts and legal, hiring and people decisions, deleting/cancelling/sharing, someone new (an address on neither the roster nor the contacts) and big sends (a broadcast or department message, or more than five people). On top of these, the company (set by the principal) and each person (for their own As you) add structured rules: a person or address, a domain, words, or an amount at or above a figure. Added rules always hold, and an error reading them holds the action. The one thing the gate lets straight through is a direct message (`message_person` or a Slack, Telegram or Discord DM) whose only recipient is the principal (`_only_to_principal`): they are who it would wait for, so a card would only ask them to approve a message to themselves. Anything that reaches or acts on anyone else is checked, and a roster that can't be read is not the principal. A held action becomes a `take_the_lead_action` decision instance with a companion `DECISION_ALERT_SOURCE` card on Today, routed to the first teammate holding one of its People approval ranges (`take_the_lead.approval_ranges`, plain code, closest fit first: money to `spend_lt_2k`, `spend_lt_10k` or `spend_gt_10k` by its largest amount, with a higher range able to approve a lower one and no amount read as large, or to `customer_credit` for credit and payment terms; vendor contracts to `vendor_onboarding` then `legal_sign`, other contracts to `legal_sign`; hiring to `hiring_signoff`; anything else about the board or investors to `board_comms`; in Personal as in team mode), or else the principal through the authority gate's fallback (`departments.authority._route_proposal`). Deletes and shares always go to the principal. Only the principal and that approver see or resolve it (`DecisionClassSpec.principal_and_approver`). Approving it claims the row and carries out the exact call once (`take_the_lead.carry_out`: the unwrapped handler, or the gateway's `call_tool`, on an unattended session, with contact egress only when the principal approves). Declining drops it. Everything done or held is a row in `take_the_lead_log`. What it did and what was approved show in Recent activity (`today._build_activity`, kind `took_the_lead`), named but never quoted, since that feed is the team's. The held card's own `decision_resolved` row is left out because its payload quotes the message. `GET /today/activity` also adds the caller's own Handle it sends (kind `sent_as_you`, actor `you`), which are never in the shared feed.\n\n**In training.** The As the Executive switch has three positions: Off, **In training** and On (`take_the_lead.training`). In training, an action the gate would let through still waits, as a `training` hold for the principal alone, unless the principal has allowed that action with that person or thing (`take_the_lead.allowance`: \"Message Priya Nair\" covers a message to her on any channel; \"Book meetings with Priya Nair and Sam Lee\" meetings with exactly them; a workflow by id; a connected tool by name and the file it names, never one that reaches people such as a mail send or a share). The card carries Approve, **Approve + allow**, **Edit** (the message, a meeting's title, times or description, a task and its due date: `take_the_lead.apply_edits`) and Decline. Allowing is the principal's alone and needs a request the API can tie to them, as turning it on does; the six kinds and the added rules hold whatever is allowed. An edit approved with \"Do it like this next time\" is kept as an example (only the edited text, the principal's own words), and `take_the_lead.learned_note` hands the examples and the fact it's in training to the reflection and research passes in their user turn. After `SUGGEST_AFTER` (3) unchanged approvals of the same action in 30 days, Settings suggests allowing it. What it's learned is one list keyed by feature (`take_the_lead_allowed.feature`), so other features that learn from approvals can join it; each keeps its own switch. Act as me is the second (`act_as_me`, per person, `delegation.training`), with a training switch per setting (Replies, Follow-ups, Suggested actions, Drafts): its rows carry the person's id and the setting in their key, are listed and removed by that person alone, count toward their own cap, and never reach `learned_note`.\n\n**AI disclosure.** Nothing the Executive sends to people outside the web chat goes without saying it is an AI: plain code adds the line in the MCP gateway (mail) and at each chat send (Slack, Telegram, Discord, Google Chat replies, its DMs and room posts), never the prompt, so the persona and the cached system blocks are unchanged and a reply the model writes can't drop it. Replies the inbox watcher writes as a person carry their own line by that person's switches. See Integrations → **AI disclosure** and Act as me → **AI line on replies**.\n\n**App control from chat** (`orchestrator/app_control.py`, catalog in `orchestrator/app_control_catalog.py`). Three tools in the `app` tool group let the Executive do what the app's buttons do when the person asks (\"pin this\", \"delete that chat\", \"turn off Handle it for me\"): `find_in_app(kind, query)` lists what the speaker may change (their chats, topics, documents, workflow runs, settings; files, memory, departments, skills and workflows for the principal), `do_in_app(action, id, value)` does one action (`id: \"this\"` is the chat they are in), and `open_in_app(screen)` returns an in-app link. Each action calls the API route its button calls, as a function, with a request naming the turn's verified speaker (`correction_tools._speaker`; an email or unattended turn gets a refusal), so the route's own checks decide what this person may do. Actions whose route checks nothing about the caller (their page is the principal's) are `principal_only`. Deletes, shares, turning on Act as me, Handle it for me or Take the lead, removing a Take the lead rule, clearing every card and approving a workflow's waiting step never run in the turn: they become an `app_action` decision card, private to the speaker, shown under the reply; the tap runs the action with the tapper's own request through `POST /decisions/{id}/approve` (claimed once; a card older than a day is turned down). After a turn reads outside text or the speaker's mail, every action becomes a card. The tools are withheld from unattended and AI-app turns, and `do_in_app` from a shared chat someone else spoke in. Snoozing a card uses `ack_alert`'s trust rule: only ids the server showed or found this turn. Extensions add kinds, actions and screens with `register_kind` / `register_action` / `register_screen` at startup. The person's notes stay with `recall_history`; account, sign-in and billing stay on their screens.","mermaid": "flowchart TD\n User([User message]) --> Exec[\"Executive<br/>orchestrator\"]\n Exec -->|consult_specialist| Cso[\"cso: StrategyAgent\"]\n Exec -->|consult_specialist| Cfo[\"cfo: FinanceAgent\"]\n Exec -->|consult_specialist| Gc[\"gc: LegalAgent\"]\n Exec -->|consult_specialist| More[\"chro / coo / cmo / cpo / sales<br/>board_comms / triage\"]\n Mode{{\"Team or solo<br/>(persona + tools per turn)\"}} --> Exec\n Exec -->|\"ghostwrite_email (Act as me)\"| Gw[\"ghostwriter<br/>(tool-less, not a Council agent)\"]\n Cso --> Claude[\"Claude (Anthropic)\"]\n Cfo --> Claude\n Gc --> Claude\n More --> Claude\n Claude --> Exec\n class User entry\n class Exec compute\n class Mode compute\n class Cso compute\n class Cfo compute\n class Gc compute\n class More compute\n class Claude external\n class Gw compute",- "generated_at": "2026-10-18T12:45:41Z"+ "generated_at": "2026-10-18T19:37:35Z"}diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.jsonindex 12332d9a..a9afc4bd 100644--- a/packages/core/openexecutive/architecture/prebuilt/api.json+++ b/packages/core/openexecutive/architecture/prebuilt/api.json@@ -1,7 +1,7 @@{"section_id": "api","title": "API Reference",- "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). A request it lets through is marked `request.state.shared_secret_ok`, which is what lets an MCP request turn on \"may act\" with `x-mcp-client-actions: on` (`mcp_server.may_act`; with no secret the header is ignored and `MCP_CLIENT_ACTIONS` decides). With local login (`OE_LOCAL_LOGIN=1`, which only `make dev` sets, and only while neither Google nor SSO sign-in is set up) a second middleware answers 403 to any request whose raw `Host` is not `localhost`, `127.0.0.1` or `[::1]` (except a webhook that verifies its caller: Google Chat and Slack always, Telegram only with a `TELEGRAM_WEBHOOK_SECRET` Telegram can send), and to any write whose `Sec-Fetch-Site` is present and not `same-origin`/`none`. The UI signs that owner in with no password and this API usually has no secret, so without it a web page in the owner's browser could drive the API as the principal — by DNS-rebinding its own hostname to 127.0.0.1, or by posting a plain form from another site or localhost port. CORS is restricted to the UI origins in `BACKEND_ALLOWED_ORIGINS`, plus the `make dev` UI on `localhost:3000` only when `OE_PUBLIC_DEPLOYMENT` is unset, so a public instance never answers a localhost page with credentials. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\n**Who is calling** is read in one place, `api/caller.py`, which answers with a `Caller` kind and email; a test fails on any other read of an `x-caller-*` header. By default (`open`) it is the `x-caller-email` the UI proxy stamps from the sign-in, trusted because whoever holds the shared secret is trusted as the proxy, and a request with none runs as the principal. **Signed callers** remove that trust. With `CALLER_ASSERTION_PUBLIC_KEYS` set, the proxy signs every request with an Ed25519 key only the UI holds, and a third middleware checks the `x-caller-assertion` header:\n\n- **What it covers.** It is good for one method, the exact path and query, at most 120 seconds, and one use. The API keeps used ids in memory.\n- **What it names.** A `user`, by email, or the `operator`: local login, which runs as the principal.\n- **No caller header at all** is a `service`, for scripts or MCP clients holding only the secret. It is never the principal, not even on an install with no owner yet, so it can't save a first setup.\n- **Anything else is a 401.** That includes an `x-caller-email` without an assertion (`caller_assertion_required`), and a bad, expired, reused or mismatched assertion (`caller_assertion_invalid`).\n\nPublic keys that can't be read stop the boot, rather than fall back to trusting the header. `scripts/make-caller-keys.py` makes the pair, and `scripts/mint-caller-assertion.py` signs one request for curl. The API holds only public keys. Setup's API-protection check warns while a shared secret is set without them.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat`, `POST /chat/stop`, `POST /chat/add`, `POST /chat/background`, `GET /chat/voice`, `POST /chat/transcribe` | SSE stream of a live Executive turn, with a `: keepalive` comment every `CHAT_STREAM_KEEPALIVE_S` while the turn is quiet. `POST /chat/background` starts a new chat that the server answers to the end with nobody connected (a phone approving a card, then closing the app): it answers `202` with the new `session_id` once the same caller, access and quota checks as `/chat` pass, the turn saves itself as a `/chat` turn does, and one caller may have three running at once (`429` beyond that). `POST /chat/add` hands the running turn a message the person typed while it works; the turn takes it at its next step and the stream names it in a `message_added` event, and a second `POST /chat` on the same conversation waits for the first to finish. `GET /chat/voice` says whether the chat mic shows (`available`, `max_seconds`); `POST /chat/transcribe` takes one recording (multipart `file`) and answers `{text}` for the message box, nothing kept: `404` when speech to text isn't set up, `400` for a file that isn't audio, `413` over 25 MB, `502` when the speech server fails. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. Each round of tool calls also emits an `activity` event (`{type, label, tool, iteration}`) naming what is running — progress only, forwarded verbatim and never persisted with the message, unlike an `action_taken` chip. A `session_id` in the body must be a chat the caller may use (the same ownership rule as `sessions`). If it isn't, the turn runs in a fresh chat instead, so nothing is written into someone else's session and the reply looks the same as for an unknown id. An unknown namespaced id (`slack:…`, `telegram:…` and so on) is ignored and a fresh chat is started, because those ids belong to the channel adapters and claiming one first would make the caller its owner. The client mints a `client_turn_id` and sends it with the turn; `POST /chat/stop` takes that id and halts the turn mid-flight, so the button is live from the moment Send is pressed rather than only once the first SSE byte arrives. A stopped turn emits a `stopped` event and then the usual `done` over the same still-open stream — never an `error` — and whatever streamed so far is persisted and flagged. The endpoint returns 404 both for an unknown id and for another caller's turn, so it cannot be used to probe which turns are live. An optional `memory_text` (1–2000 chars) is what peer memory records as the caller's words instead of `message` — the briefing handoffs send it because their seed quotes the Executive's own card; `POST /chat/upload` derives it from the typed text and filenames. Since it never reaches the transcript, the `chat_turn` audit row keeps it beside `message`. After the reply — a stopped or timed-out one too, before the `stopped` / `error` / `done` frames — a turn that looked at anything sends one `sources` event, `{type, session_id, sources: [{kind, title, url}], unavailable: [area]}`: `kind` is `company`, `knowledge`, `notion`, `research`, `document` or `web`, `url` is only ever an http(s) link or, for an earlier document, `/artifacts/<id>`, at most 12 sources (6 from the web, pages the reply cites first), and `unavailable` names parts of the analysis (\"finance\") whose specialist failed or said nothing every time it was asked. It is persisted with the reply as `chat_messages.sources`. A request that carries `x-caller-email` marks its turn signed in (`Session.web_caller_signed_in`), which Act as me needs on a deployment without local login. |\n| `sessions` | `GET /sessions`, `GET /sessions/shared-with-me`, `GET /sessions/topics`, `PATCH\\|DELETE /sessions/topics/{topic_id}`, `POST /sessions/topics/{topic_id}/merge`, `POST /sessions/topic-areas/rename`, `POST /sessions/topic-areas/ungroup`, `GET\\|PATCH /sessions/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup`, `GET\\|PUT /sessions/{id}/shares`, `DELETE /sessions/{id}/shares/me`, `GET /sessions/{id}/people`, `GET /sessions/{id}/live`, `POST /sessions/{id}/typing`, `GET /sessions/{id}/export`, `POST /sessions/{id}/rewind` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller, and each chat carries `preview`: its last message as one plain line, Markdown marks stripped and cut at a word near 120 characters, with `You:` before the person's own words. With `?q=` it is a search: the caller's own chats whose title or message text contains the words (case-insensitive, `LIKE` with wildcards escaped), each with `match_count` (messages that contain them; 0 for a title-only match) and `snippet` (the newest matching message, around the match, prefixed `You:` or `Executive:`). Scoped exactly like the list, so nobody else's conversation can match. The Chats page searches this way and opens a result with `?find=`, so the chat starts on that message and steps through the others. Each of the owner's chats also carries `topic_id`, the topic it is filed under (`memory.chat_topics`). `GET /sessions/topics` lists the caller's topics (`id`, `name`, `chat_count`, `kept`, `pinned_at`, `area`, `updated_at`) and, when some of their chats have no topic yet or some topics no area, starts filing them in the background from their titles and answers `organizing: true` until done. `PATCH /sessions/topics/{topic_id}` renames (a name another of their topics has merges the two) or pins one, `POST …/merge` moves its chats into another (`into_id`), and `DELETE` ungroups it, leaving its chats under no topic; another person's topic is a 404. `POST /sessions/topic-areas/rename` (`area`, `name`) renames one of the caller's areas and `…/ungroup` (`area`) drops it, its topics standing alone; an area they don't have is a 404. `PATCH /sessions/{id}` also takes `topic_id` (null for none) or `topic_name` (made if new) to file the chat, which then is never refiled on its own. A chat-app conversation started with /new is left off the list until its first turn (`memory.conversations`). Every per-session route checks ownership, because session ids are guessable (`slack:dm:<user id>`, `telegram:<chat id>`): only the session's owner or the principal gets through, and a legacy row with no owner is the principal's alone. A teammate's own chat (a web chat, a DM, a private Telegram chat; not a channel or group conversation, `chat._shared_space`) is theirs alone, the principal included, as their mail with the Executive is. Anyone else gets the same 404 as for an unknown id, so the routes can't be used to find out which chats exist. The one other way in is having started the chat in this process (matched by Person id or verified email, so it survives the caller being added to the roster), which is how a caller the roster can't resolve keeps using their own chat. That record is in memory, so after a restart such an ownerless chat is refused for reads. The principal can continue someone else's ownerless chat without becoming its owner. Deleting a session also drops its in-memory copy, so a later turn naming that id starts fresh. The feedback route records 👍/👎 (`{\"feedback\": \"up\"|\"down\"|null}`) on one assistant reply; only the session's own caller or the principal may rate it. The rater is stored (`feedback_by_person_id`), and a 👎 on a reply to the rater's own message triggers a working-style pass for them (paced; see attunement). The chat stream's `done` event carries `message_id` for the persisted reply. The followup route returns `{\"suggestion\": string|null}` — one suggested next user message, written by the utility-fast model from the last few turns, that the chat composer shows as its greyed placeholder (Tab / → or the inline chip fills it in without sending). It is null unless the session ends on a persisted assistant reply, and null (uncached) when the model fails. Same ownership check as feedback; successful suggestions are cached in-process per (session, reply id). Messages from `GET /sessions/{id}/messages` carry each assistant reply's saved `sources` (the same shape as the chat stream's `sources` event, without `type`), so a reloaded chat shows them again. The owner (not the principal on someone else's chat; the principal for an ownerless one) also has the chat controls. `PATCH` takes `{title?, pinned?}`: a name they give is kept (`sessions.title_locked`, so the automatic title never replaces it) and a pinned chat lists first, newest pin first, with `pinned_at`. `PUT /sessions/{id}/shares {person_ids}` adds exactly those team members to it (not contacts, the archived or the owner: 422), audited `session_shared`; a chat that read its owner's own mail (`mail_private`) is never shared (409) and stops being open to those it was shared with before, and a chat-app conversation is never shared (409). Those added get it from `GET /sessions/shared-with-me` (with `shared_with_you`, `shared_by`, `shared_at`) and **write in it with the owner**: `POST /chat` with its id runs their turn as themselves (`chat._shared_member` widens the turn's access, never its ownership), and they may read it, its messages (without the owner's ratings) and its export. They can't rate, rename, delete, share or redo it, and `DELETE /sessions/{id}/shares/me` takes them out of it (audited `session_shared`, with them under `removed`). In a chat several people are in, messages carry `sender_person_id` and `sender_name` (a message from before it was shared is the owner's), `GET /sessions/{id}/people` returns `{you, people: [{person_id, full_name, owner}]}` (owner first; empty for a chat of one), and redo is refused (409) when the last message is someone else's. `GET /sessions/{id}/live` is a server-sent event stream each open page holds (`api.chat_live`, one in-process broker): `ready` first (with the running turn so far, if any), then `turn_started` (who sent what), the reply's `chunk` / `thinking` / `activity` / `action_taken` / `phase`, `turn_ended` (the page reads the chat again), `typing` (from `POST /sessions/{id}/typing`, at most once per 2 s per person) and `people`. `removed`, `deleted` and `resync` (a page that fell 1024 events behind) end it; the access check runs again on every 20 s keepalive. At most 12 pages per person, 40 per chat and 2000 per process (429). Archiving someone takes them out of every chat shared with them, and their open streams close at the next keepalive. The page closes it while its tab is hidden. `GET /sessions/{id}/export` returns the chat as a Markdown file (`memory.chat_export`: each message under its writer's People name or `Executive`, the reply's sources listed under it). `POST /sessions/{id}/rewind {last_message_id}` takes back the last turn for Try again and Edit: under the conversation's turn lock it deletes the last reply and the messages it answered, but only while that reply is still the chat's last row, and returns those messages' words (`{message}`), which the page sends again as an ordinary `/chat` turn through the usual gates. 409 while a turn is answering, for a stale reply id, and for a chat-app conversation (its reply also lives in Slack, Telegram or Discord); audited `session_rewound`. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/value`, `GET /today/top-three`, `GET /today/weekly-review` | Morning-brief aggregation (in the install's first week, for the principal, `first_week_card` `{needs_goal, findings: [{title, summary}], brief_tomorrow}` or null), recent-action rail, Pulse heartbeat heatmap (per-day activity counts), and the owner's month tally for Pulse's Done for you (`GET /today/value?period=month|week&offset=N`: counted lines beside the period before plus the finished reports, owner only, 403 otherwise; see Today). `GET /today` carries the viewer's cached \"What's going on\" `narrative` with `narrative_generated_at` (when it was written) and `narrative_stale` (a fresher one is being written — the page re-polls; see Today). A proposal backed by a roster request carries `roster_request` (the new sender's server-derived details and held-message previews; the principal's only) and is answered through the `people` routes below. `brief-delivery` returns the latest morning brief or end-of-day digest that didn't reach the owner, as `{brief, at, problem, fix, readable}` in plain language (`readable` is false when it couldn't be written, so there is nothing to read), or null — null while briefs go out, once the cause is fixed, while the scheduler is off, and for anyone but the owner (`chat._caller_is_principal_or_unclaimed`); it carries no address or channel id. `top-three` and `weekly-review` feed the solo Briefing's own cards and answer only in solo mode and only to the principal (`workflows._caller_is_the_principal`: a principal match or no caller header, never an unclaimed roster); anyone else, and team mode, get null. `top-three` returns `{items: [{key, kind, text, why, slot}]}` — the morning brief's top three from the same code (`build_top_three(principal_due_soon())`), `slot` a free block like `10:00–11:00`, `\"\"` when none is left, null when no calendar was read — and is kept off `GET /today` because its calendar read may take up to 4 s. `weekly-review` returns the latest completed `weekly_review` run as `{run_id, completed_at, period, top_three, excerpt}` (next week's top three as plain text; `excerpt` when that list is empty), or null when none has completed. |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive`, `GET /people/requests`, `GET /people/requests/{id}`, `POST /people/requests/{id}/approve`, `POST /people/requests/{id}/decline`, `GET\\|POST /people/{id}/open-loops` (a `POST` tells the owner once and returns `notified`: `sent` with the channel, `held`, `not_reached` or `skipped`; see Attunement), `POST /open-loops/{loop_id}/close`, `GET /people/{id}/outreach`, `GET\\|PUT\\|DELETE /people/{id}/attunement` | Roster CRUD and scope lookups. Every `Person` carries `kind` (`team` / `contact`). `GET /people` lists team members only unless `?include_contacts=true` (the People page asks for both; the department-head and workflow pickers keep the default); `POST` / `PATCH` accept `kind`, and a principal contact is a 422 either way. They also take `email_aliases` (other addresses the person writes from, at most 10; on `PATCH` the full list replaces the current one, omitted leaves it): an alias matches their mail and may be emailed but never signs in; a malformed one is a 422, and an alias — or a new primary `email` — that is already someone else's address or alias is a 409. Every `POST` / `PATCH` then closes any pending roster request whose sender now matches someone and replays its held messages. Adding, editing and archiving (`POST`, `PATCH`, `/archive`) are the principal's only, or anyone's while no one is principal yet so a first setup can add its owner (`chat._caller_is_principal_or_unclaimed`, the check behind `PUT /workspace`; a request with no `x-caller-email`, such as the CLI or local login, counts as the principal). Anyone else, a person editing their own row included, gets 403 before the person lookup, so it can't probe which ids exist. Contacts are private to the principal (`caller_is_principal`: the signed-in email is the principal's, or no `x-caller-email`; stricter than the owner rule above, so while no one is principal nobody is): for anyone else `include_contacts` is ignored, a contact's id is a 404 on `GET /people/{id}` and open-loops (exactly as for a missing id; `PATCH` and archive are already a 403 for them), and creating a contact or turning someone into one is a 403, even on a first setup with no principal yet. `GET /people/me` returns `{person_id, is_principal}` so the UI offers contacts to the principal only. `GET /people/by-scope/{token}` never returns a contact. Archiving a person closes their open loops. The open-loop routes list what a person owes (soonest due first) and close one (`reason`: done / not_needed / cancelled) — both the principal's or the owner's only (403 otherwise, via `people.store.is_principal_or_self`). `POST /people/{id}/open-loops` `{task, due_date?}` assigns that person a task (201 with the loop; `due_date` is a local date, due 17:00 in the user's timezone, clamped to 60 days, default 2 days): any active team member may assign anyone on the team, 403 for anyone else; 409 for an archived person, a contact (as seen by the principal), a person at the open-loop cap, a duplicate or open loops turned off; 422 for an empty task. Nobody is messaged at assignment — the owner is chased once it is due. `/outreach` returns, per kind of proactive outreach over 30 days, `sent` / `replied` / `acted` / `ignored` / `pending` (voided DMs are excluded) — same access rule, checked before the person lookup so it can't probe which ids exist. `/attunement` reads, replaces (`rules`: up to 4 strings, or omitted to only set `locked`) or resets the person's working-style rules — same access rule, 404 for an archived person; `PUT` rejects a rule that is not purely about style with 422. Archiving a person also drops their working style and frees their aliases. The **roster-request** routes (declared before `/people/{person_id}`) are the principal's alone (`caller_is_principal`; anyone else gets 404, as for a missing id): `GET /people/requests?status=pending|approved|linked|declined|expired|superseded|all` lists up to 100 (`id`, `channel`, `channel_ref`, sanitised `display_name`, `profile_email`, `on_company_domain`, `suggested_kind`, `suggested_person_id` / `_name`, `status`, `resolved_person_id` / `_kind`, `message_count`, timestamps, `ack_sent`, and `previews` of the held messages while pending — shown to the principal, never to a model); `approve` takes either `link_person_id` (+ `replace_channel_id`) or `full_name` + `kind` (no default: 422 without both) + optional `role`; `decline` takes no body. An answered request is a 409, a chat id or address already on someone else is a 409; the held messages are replayed (or dropped) in the background. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals`, `POST /goals` | Department state and per-department goals. `POST /goals` takes a goal plus `area` (a name, ≤80): an existing area by slug or title, else a new one of that name (no specialist, as with `POST /departments`), else **General** when blank; the Goals page uses it while a workspace has no areas (setup makes none for solo or a team that names none). `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. A `cadences` spec that does not parse is rejected with a 422 (empty means no cadence, i.e. the check-in is off); a changed `check_in` cancels the pending check-in and queues the next one on the new schedule. `GET` and `PATCH /departments/{slug}` return the department state plus `next_check_in_at` (ISO UTC of the pending check-in, `null` when it is off, the workspace is solo or none is queued); the list route does not carry it. A new `head_person_id` must be a team member: an unknown id and one of the principal's contacts get the same name-free 422 (`person_id N is not on the team.`), so the route — open to any signed-in user — never reveals that a contact exists; an unchanged head is not re-checked. `POST .../goals` requires only `key_result`: a missing or blank `period_value` is filled with the current period for `period_type` in the user's zone (the same label `create_goal` uses), and `target` defaults to empty. `PATCH .../goals/{id}` rejects a blank `key_result` or `period_value` with a 422; `target` may be cleared. |\n| `agents` | `GET /agents`, `GET /agents/models`, `GET /agents/models/options`, `GET /agents/presets`, `POST /agents/presets/{id}`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. `/agents/models` is the flat model allowlist the PATCH validator uses; `/agents/models/options` returns the same ids in the same order, each tagged with `provider`, `provider_label`, `route` (`direct` / `openrouter` / `local`) and a display `label`, for the Council's Provider → Model picker. `AgentDetail` carries `instructions` (additional instructions, appended after `prompt`, which stays the built-in prompt or its replacement); `PATCH` and `/test` accept `instructions` (max 4,000 chars, blank clears it). `GET /agents/presets` lists the Fast, Balanced and Thorough quality presets (each with `available` and the resolved `model` for this install) plus `active` (null when the council is Custom), `base` and `custom_agents`; `POST /agents/presets/{id}` applies one by writing per-agent model and deep-reasoning overrides and returns the same shape (404 unknown preset, 409 when the install allows none of its models). Each `AgentMeta` carries `visibility` (`core` or `internal`) so the Council's simple view can list core agents first. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/approve`, `GET /alerts/approvals/{id}`, `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/snooze`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `approve` (body `{edited_body?}`, 202) carries a proposal card out on the server and records who approved it and when (`alerts.approvals`, see Today): it queues the scheduled action a department-gated card held, or runs one Executive turn as the approver in a new chat (`session_id`). 409 for a card already approved or closed, a decision-backed card (approved at `/decisions`), a roster request or a drafted artifact; 403 unless the caller is the card's routed person or the principal (an unrouted card is the principal's); 429 when the caller already has three background turns running. `GET /alerts/approvals/{id}` reads one back (`running`, then `done` / `failed` with `outcome`) for its approver, the card's person or the principal (404 for anyone else). `snooze` (`until`, an ISO time up to 30 days ahead; `null` clears it, the Undo) hides an `unread` card until then by setting `snoozed_until` (409 on a closed card or a roster request); the TTL then counts from the snooze, so a card snoozed past its TTL still comes back. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `GET /artifacts/{id}`, `GET /artifacts/{id}/download?as=`, `POST /artifacts/{id}/archive`, `POST /artifacts/{id}/restore`, `DELETE /artifacts/{id}` | Browsable deliverables in any format — Markdown, HTML, Word, Excel, or a link into a connected app — with `format`, `downloads`, `external_url`, `supersedes_id` and, for an extension's kind of document, `collection` / `collection_label` on every summary (`orchestrator.extensions`; archive, restore and delete tell the collection first and answer 502 if it refuses). `download` renders the file (Word/Excel built at request time from the stored text; any Markdown artifact, workflow output included, can export `?as=docx`) and is always an attachment with `nosniff` and a sandbox CSP. Every route answers for the signed-in caller (`artifact_records.Viewer`): a drafted artifact is its owner's alone (`alerts.owner_person_id`, the person whose conversation published it; none = the principal's), a workflow output follows its run (`persistence.run_visible_to`), and anything the caller may not see is a 404 like a missing id, the principal included. `POST /alerts/{id}/ack` and `/reopen` answer 404 for someone else's drafted artifact the same way. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET`/`PUT /decisions/classes/meeting_scheduling`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). What approve/reject/cancel do is per class (`DECISION_CLASSES`, one `DecisionClassSpec` each; meeting booking books on approve and deletes on cancel; `delegation_reply`, an inbox reply card, is its approver's alone (`approver_only`) — hidden from everyone else, the principal included when it is a team member's — sends its Gmail draft on approve and, after a reject, deletes the draft unless it was edited; `department_action`, a team member's chat send or edit their department held (see Org), is the principal's and its approver's alone (`principal_and_approver`), makes that exact call on approve and audits `department_action_done` / `_failed` / `_declined`), and an instance of a class with no spec gets 409 instead of being carried out as another. Only the principal, or the person the decision went to for approval (`approver_person_id`), may approve, reject or cancel it. Anyone else gets 403, and a decision nobody was asked about, or one private to the principal, is the principal's alone. The resolver is recorded as `resolver_person_id`, and a reject that loses the race to another answer is a 409. `GET /audit/reliability` is the principal's alone (403 otherwise), because it counts private decisions too. A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. An approval whose caller resolves to the principal runs the booking inside `grant_contact_egress()`, so a meeting the principal proposed with a contact can be created. Such a booking's payload is marked `private`: it is proposed to the principal, left out of anyone else's `GET /decisions`, and a 404 for them on `GET /decisions/{id}` and every action route. Reviewed in the briefing — there is no separate proposals page. The class routes read and set how meetings are handled: both return `{decision_class: \"meeting_scheduling\", mode: \"propose\" \\| \"auto_execute\"}` (default `propose`); the `PUT` body is `{mode}`, principal-only (403 otherwise, open before a principal exists — but then only `propose` can be set: `auto_execute` is a 409 until a non-archived principal is on the roster), 422 on any other mode, and a change writes a `decision_class_mode_changed` audit row. In solo mode the class mode decides a booking, and `auto_execute` applies only to a turn the principal started on a verified surface — any other turn gets a proposal. |\n| `delegation` | `GET`/`PUT /delegation`, `GET`/`PUT`/`DELETE /delegation/voice`, `POST /delegation/voice/learn`, `POST /delegation/voice/describe`, `POST /delegation/voice/signature`, `PUT /delegation/inbox`, `POST /delegation/inbox/check`, `GET /delegation/replies`, `PUT /delegation/replies/{id}/text`, `GET /delegation/actions`, `PUT /delegation/handle-it`, `PUT /delegation/disclosure`, `PUT /delegation/training`, `DELETE /delegation/learned/{id}`, `GET /delegation/handled`, `PUT /delegation/team` | Act as me — the **caller's own** delegation only; nobody sets it for anyone else. It answers the principal, and a team member once the owner lets them; anyone else gets 403 `not_available_yet`. `GET /delegation` returns `{enabled, gmail: {status, message, email, connect_command, outlook_connect_command, provider}, inbox: {enabled, status, message, watch_since, last_poll_at, checking}, handle_it: {enabled, mode, available, sent_today, lead, lead_available}, training: {replies, follow_ups, actions, drafts, learned}, disclosure: {enabled, handle_it, approved_sends, line}, team}`, where `team` is the owner's switch for the principal while `DELEGATION_TEAM_MEMBERS` allows it — `{enabled, members: [{person_id, name, enabled, inbox, drafts_30d, sent_30d}]}`, counts only — and `null` otherwise. `PUT /delegation/handle-it` takes `{enabled?, mode?}` (`mode` is `careful`, `balanced` or `bold`; anything else is a 422 `bad_mode`) from a caller the API knows is that person — 403 `not_yours`, 409 `caller_signing_required` with only the shared secret — and turning it on needs Act as me and Draft replies to my inbox on (409 `act_as_me_off` / `inbox_off`); `GET /delegation/handled` returns `{replies: [{decision_id, sent_at, to_name, to_email, subject, body, open_questions, gmail_link, source}]}`, the caller's replies and follow-ups (`source` `follow_up`) sent on its own in the last 7 days; a card on `GET /delegation/replies` carries `source` the same way, `can_allow` while Replies (Follow-ups, on a follow-up) is in training, and `learns_style` while Drafts is. `PUT /delegation/disclosure` takes `{handle_it?, approved_sends?}` (any other field is a 422), the caller's own switches for the AI line on replies sent as them (`disclosure.enabled` is the install's `AI_DISCLOSURE`); turning one on needs no signed sign-in, turning one off does (409 `caller_signing_required`), and a change is audited as `delegation_disclosure_changed`. `PUT /delegation/training` takes `{replies?, follow_ups?, actions?, drafts?}` (any other field is a 422) and returns the `GET /delegation` shape; putting Replies or Follow-ups in, or Suggested actions out, needs no signed sign-in, anything else does (409 `caller_signing_required`), and putting Replies or Follow-ups in turns Take the lead as you off (`PUT /delegation/take-the-lead` on answers 409 `in_training` while they are). `training.learned` is `[{id, label, setting, example, uses, created_at}]`, what the caller allowed or kept in training (`setting` `replies`, `follow_ups`, `actions` or `drafts`; the kept example, or \"\"); `DELETE /delegation/learned/{id}` removes one of the caller's own (404 for anyone else's). `PUT /delegation/team` takes `{enabled}` from the principal alone (403 `principal_only`; 409 `not_available` when the install doesn't allow it). The Gmail `status` is `connected`, `not_configured`, `needs_reconnect`, `mismatch`, `no_email`, `shared_mailbox` or `error`, checked live with Google on each call. `PUT` takes `{enabled}` (any other field is a 422); turning it on needs the caller's own Gmail connected, otherwise a 409 whose code says why (`gmail_not_connected`, `gmail_needs_reconnect`, `gmail_mismatch`, `no_email`, `shared_mailbox`, `gmail_error`). The voice routes show, learn (from the caller's sent mail, one pass at a time — a 409 `in_progress`, `locked`, `too_soon`, `not_enough_mail`, `no_profile` or `changed` when it was locked or edited while learning, or a Gmail code), write it from the caller's own description (`POST /delegation/voice/describe` with `{description}`: one model call applies their words to the profile they have and returns it with a short `sample_reply`, saving nothing, so they review it and save it with `PUT`; a 409 `empty`, `too_long`, `in_progress`, `too_many` past 10 an hour or `no_profile`; no mailbox needed), edit and lock, and reset \"How I write\": a typed field that fails validation is a 422 `invalid_voice` listing each `rejected` field, and `clear_exemplars` / `clear_signature` drop those. `POST /delegation/voice/signature` reads the signature from the caller's Gmail settings again and changes nothing else (a locked profile stays locked), with the same Gmail codes as learning: a 409 when their mailbox isn't connected, it refuses the sign-in or the check itself fails (`gmail_error`), and a 502 `gmail_error` when reading the signature fails. On an Outlook mailbox it is a 409 `signature_unavailable`, since Outlook gives apps no signature to read, and the stored one is left alone. A caller `can_delegate` refuses — anyone but the principal, for now — gets 403 `not_available_yet`, which hides the Settings card. A request with no `x-caller-email` is a 403 `sign_in_required` unless the API runs under local login — a header-less call is not a sign-in (the caller is read through `api/caller.py`, as on every principal-only route). `PUT /delegation/inbox` takes `{enabled}` and turns **Draft replies to my inbox** on or off, returning the same shape as `GET /delegation`: on needs Act as me on (409 `act_as_me_off`) and the mailbox connected (the Gmail codes above, which keep their names for an Outlook mailbox too), and turning Act as me off turns it off too. `POST /delegation/inbox/check` starts a scan now in the background and answers 202 with the `inbox` state (409 `inbox_off` or `in_progress`). `GET /delegation/replies` returns `{cards: [...]}`, the caller's open reply cards from the database alone (no Gmail call): the decision id, the sender's name, address, relation and whether it was verified, the subject, when it arrived, what they wrote, the draft's recipients, subject and body, `open_questions`, `flags` and a Gmail link built from a fixed prefix. **Send** is `POST /decisions/{id}/approve`: it sends the card's draft exactly as it is in Gmail, after checking again that the caller is its owner — which on a server needs signed callers (409 `caller_signing_required` otherwise) — that both switches are on (`inbox_off`), no client slot is active (`client_slot`), the Gmail is connected (the Gmail codes), the draft is still there and unanswered (`draft_gone`, `you_replied`) and its recipients are allowed (`no_recipients`, `too_many_recipients`, `executive_recipient`, `not_from_you`). Recipients that changed, or a newer message in the thread, answer 409 `{code: \"confirm\", message, reasons, recipients}`; approving again with `edits: {recipients: <the list shown>, thread_moved_on: true}` is the second yes. **Send + allow** adds `edits.allow: true`: 422 `cant_allow` unless Replies (Follow-ups, on a follow-up card) is in training, 409 `learned_full` when their list is full, both before anything is sent; `edits.example: true` keeps a draft edited in the mailbox as how they write to that person while Drafts is in training. A draft edited in Gmail between those checks and the send is not sent (`draft_changed`). A double tap sends once (`already_handled`); Gmail refusing answers 429 `rate_limited` or 502 `gmail_error` with nothing sent, and a send Gmail didn't confirm answers 502 `send_unconfirmed` and is settled by the next inbox scan. Dismiss is `POST /decisions/{id}/reject`. `GET /delegation/actions` returns `{cards: [...]}`, the caller's own approval cards (`delegation_actions`): the decision id, when it was made, a one-line `why`, and each action's `index`, `kind` (`invite`, `message`, `add_contact`), `summary` and `text` (a message as it will be sent, or a meeting's description). **Approve** is `POST /decisions/{id}/approve` with `edits: {only: [indexes]}` (and `allow: true` for Approve + allow while Suggested actions is in training: 422 `cant_allow` otherwise or when nothing on it can be allowed, 409 `learned_full`; a card carries `can_allow`); it needs the card's own person signed in (403 `not_yours`, 409 `caller_signing_required`), Act as me on (409 `act_as_me_off`) and a card under a week old (409 `expired`), runs once (409 `already_handled`), and returns the decision with `final_payload_json.results`: per action `done`, `waiting` (sent to whoever approves meetings), `failed` with why, or `skipped`. Every change writes a private audit row. |\n| `history` | `GET /memories/history` (`?q=`), `PUT /memories/history/settings`, `PATCH`/`DELETE /memories/history/{id}`, `POST /memories/history/{id}/forget-conversation` | Always in the loop: the **caller's own** notes and switches only, resolved as for Act as me (a signed-in person on the roster, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{notes, reply_notes, retention_days, effective_retention_days, company_retention_days, retention_choices, can_keep_notes, can_note_replies, can_set_company_retention, share_work_style, can_share_work_style}` (`can_keep_notes`: a team member on the People list may turn notes on; `can_note_replies`: they can use Act as me, so email replies are noted too; `share_work_style`: their own \"Share my work style with the team\" switch, `can_share_work_style`: a team member in a team workspace). `PUT` turns notes on only for someone who may keep them, and `share_work_style` on only for someone who may share it (403 `not_available` for either; turning either off always works), takes a person's retention only when shorter than the company's (422 `invalid_setting`), and the company retention only from the principal (403 `principal_only`). `PATCH` pins or corrects a note; `DELETE` forgets it; `forget-conversation` is \"Don't remember this\". A note that isn't the caller's is 404. Every change is audited privately to its person. |\n| `reflection` | `GET /memories/reflection` (`?person_id=`), `DELETE /memories/reflection/misses/{id}` | What it got wrong: the turns the conversation review graded a miss (`memory.chat_review`), with the person's words, the reply, the tools run, what they wanted instead, the `kind` (`company` / `product`) and the signals, plus `weeks` (`{week, graded, misses}` per ISO week, newest first) and `sees_everyone`. The caller is resolved as for `history` (403 `sign_in_required` / `not_on_roster`); each person sees their own, the principal those from chats `chat._session_access` lets them open (a teammate's own web chat or DM and a mail-private conversation stay their owner's; channels and groups are open), or one person's with `?person_id=` (a teammate naming someone else gets 403 `not_yours`); the weekly counts carry no words and are not filtered. The same response carries `lessons` (`memory/lessons.py`: live first, then retired, each with `shown`/`fine_after`/`miss_after` and `retired_reason`), filtered by the same rule, and `DELETE /memories/reflection/lessons/{id}` retires one (204; 404 for a lesson the caller may not see, already retired, or missing). `DELETE` forgets one miss (`is_principal_or_self`; 404 `not_found` otherwise) and writes a `chat_review` audit row. Each miss also carries its nightly replay (`memory/replay.py`): `replay_state` (`open` / `closed` / `evidence`), `replayed_at`, `closed_at`, `replay_notes`; and the response carries `replay` (`{misses, would_pass, evidence, last_run_at}`: of the caller's visible misses from the last 30 days, how many would go right today). |\n| `notifications` | `GET /notifications/settings`, `PUT /notifications/settings` | Settings → Notifications: the **caller's own** settings only, resolved as for the notes (a signed-in person on the People list, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{quiet_hours: {enabled, start, end, days}, delivery, urgent_through, timezone, effective_timezone, held_count, gets_briefs, updated_at}` — `days` is `every_day` or `weekdays`, `delivery` `instant` or `digest`, `timezone` the zone they chose (`\"\"` for the workspace's), `held_count` how many messages wait for their quiet hours or brief (counted, never listed), `gets_briefs` whether they are the principal. `PUT` takes `{quiet_hours, delivery, urgent_through, timezone}` and replaces them (extra fields, equal start and end, a bad time or an unknown zone → 422); switching `digest` → `instant` makes what waited for the brief go now. Audited as `notification_settings_changed`. See Org. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts), plus `scripts`: how many `run_script` scripts ran (and worked, and in workflows), the tool calls they made, their time, and `turns_avoided` — an upper bound on the model turns those calls would otherwise have needed (each call past a script's first) — and `python_jobs`: how many Python jobs ran (and worked, ran a kept Custom tool, took a chat attachment), their time, CPU, largest peak memory and bytes in and out, and the tokens and charge of the turns that ran one. The Token usage page shows it as a Scripts section. Rows private to the principal (`private_to_principal`: a turn about their private mail, or a row naming one of their contacts on their own turn) are theirs alone: for any other caller, resolved as for `/alerts`, the usage totals leave them out. Once a principal is on the roster, anyone else reads only their own rows (a teammate's own turns, their Act as me work) in the list, by id and in a session, and the principal reads those as actions only — what was done, when and in whose conversation, with the text, details and `full` left out, and no text search over them; any other row's id is a 404, and a session shows only the rows the caller reads. |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes. Only `/health` is unauthenticated; `/health/honcho` sits behind the gate like everything else, because the exemption is an exact-path set. `/health` also carries `google_tools_missing`, the pinned Google tools startup priming could not find: `[]` once it has checked and they are all there, a list of names when a workspace-mcp rename or the configured services and tool tier left one out, and `null` for no answer — Google Workspace is not configured, or the probe has not finished or it failed. Only `[]` asserts they are present. It also carries `gateway`, the MCP gateway's state from its supervisor (`orchestrator.gateway_boot`): `state` is `off` (MCP not enabled), `no_servers` (enabled, the config names none), `starting` (an attempt is running), `up` or `down` (every attempt so far failed; `next_retry_at` is the next one), with `attempts`, `up_since` and `email_poller` (whether the poller that rides on the gateway runs); the failure's own text stays out, since the route is open to anyone, and goes to the log and the owner's notice on Home. A hosted instance whose gateway never came up used to answer `ok` here with no email going out or in. Only `[]` asserts the tools are present, so a probe that died cannot read as healthy; Setup status says which of the three `null` means. |\n| `version` | `GET /version` | The running version, the latest release on GitHub and `update_available`, for Settings → About. The GitHub answer is cached 6h, only a semver `tag_name` is used and the release link is built from it; `UPDATE_CHECK_ENABLED=false` skips the call and still returns the running version. No in-app updater: upgrading is host-side (`docs/deployment.md#upgrading`). |\n| `setup_status` | `GET /setup/status` | Settings → Setup status: one light per part of the install — AI model, company setup, owner, the Executive's address, API protection, Gmail, your own mailbox (Act as me), Slack, Discord, Telegram, Google Chat, the scheduler, the daily brief (when and where it goes) and Honcho — as `{checked_at, checks: [{id, label, state, summary, fix, link, last_activity}]}`, where `state` is `ok`, `warn`, `error` or `off` (optional and not set up), `fix` says what to do in plain language, `link` is an in-app page that helps (`/people`, `/onboard`) and `last_activity` is the channel's latest `integration_inbound` audit time. It tests live, with at most one free read-only call per service, each bounded to 5 s: Anthropic `models.list` (so an organisation key missing `ANTHROPIC_WORKSPACE_ID` shows up), Slack `auth.test`, Telegram `getMe` and `getWebhookInfo`, Discord `users/@me` only while the bot is still connecting, and — once the owner's own Gmail credential exists — Google's token refresh and Gmail `users/me/profile`. It also reads the listeners the lifespan leaves on `app.state` (Slack's socket, the Discord bot and its task, the MCP gateway), the scheduler heartbeat and the pause switch. When `google_workspace` is configured, the lifespan also starts `MCPGateway.prime_pinned_tools()` in the background (held on `app.state.mcp_prime_task`, cancelled at shutdown), so the pinned Google tools named in the prompt are callable without a search. With `DRIVE_SYNC_ENABLED` the lifespan also bootstraps the `drive_sync_scan` heartbeat beside Notion's (see Scheduler); the Drive folder sync has no HTTP route, only the `openexecutive sync-drive` / `purge-drive` CLI. With `CONFLUENCE_SYNC_ENABLED` it bootstraps the `confluence_sync_scan` heartbeat the same way; that sync is run by hand with `openexecutive sync-confluence` / `purge-confluence`. Sample values copied from `.env.example` are named as such without being sent anywhere. No token reaches a response or a log line: probes report a status code, a service's short error code or an exception's class name. Requests within 5 s of a run get that run's answer and concurrent requests share one run (kept per app on `app.state`), so the button can't become a stream of calls to those services. Gated like every other route; the UI adds a sign-in light of its own, from its own settings. |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}`, `GET /documents/sources`, `POST /documents/sources/{drive\\|onedrive\\|notion}/sync`, `GET /documents/{drive\\|onedrive\\|notion}`, `GET /documents/{drive\\|onedrive\\|notion}/{id}` | Upload, list, view extracted text, and delete indexed company docs. `GET /documents` rows carry `source: \"upload\"` and the `domain` the upload was indexed under. The connected-source routes back the knowledge page's single Company documents list: `/documents/sources` gives each source's `{id, label, enabled, syncing, last_run, last_error, interval_minutes, file_count}`; `/documents/drive`, `/documents/onedrive` and `/documents/notion` list synced files from the sync state (`{enabled, last_run, last_error, files: [{id, name, url, modified_at, synced_at, indexed}]}`; a Drive row also carries `unreadable_reason`, why a file with `indexed: false` has no text — e.g. a scan OCR could not read — or null); `/documents/{drive\\|onedrive\\|notion}/{id}` returns the stored text (a OneDrive id is `<drive id>:<item id>`) for an id on record (the path comes from the state, never the caller). They are read-only — a synced file is removed where it lives. `POST …/sync` starts one tick of the same sync the scheduler runs as a background task (202); 409 when the source is not connected or a tick is already running (every sync holds a per-process run lock, so a manual run never overlaps the heartbeat; the route also keeps its own started task per source and re-checks just before starting one, so two simultaneous requests start one tick, not two), 429 with `Retry-After` within 60 s of the last successful run or of the end of the last tick in this process, failed ones included, so a failing or slow source can't be re-run back-to-back. The page's text view never loads images from synced content (a remote image would be a read beacon for whoever edits the shared folder). Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the nine specialist domains (including `sales`) or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. A scanned PDF is converted (`knowledge.pdf_reader`) before it is indexed and in the text view, as are scanned PDFs in `POST /chat/upload` and the client / onboarding intake uploads. The upload is streamed to disk 1 MB at a time and refused with a 413 once it passes 50 MB, and the file is parsed in a short-lived child process (see the RAG section), so a large document does not stay in the API process's memory. A Word or Excel file that cannot be parsed, or whose parse runs out of time, is a 422 with a readable reason. When every parser is busy, the response is a 503 with `Retry-After`. |\n| `executive` | `GET /executive/status`, `POST /executive/pause`, `POST /executive/resume` | Operator pause switch for all autonomous work (scheduler, Gmail poller, workflow resumer); inbound chat and DMs stay live. Status returns `{paused, paused_at, paused_by, reason, held_actions, can_resume, name}` — `held_actions` counts due `pending` rows that fire on resume, and `name` is the Executive's name (`EXEC_DISPLAY_NAME`), which the web chat shows over its replies. `pause` takes an optional `reason` (≤200 chars) and is idempotent (re-pausing keeps the original start and reason); `paused_by` is the UI proxy's `x-caller-email`, else `api`. Behind the shared-secret middleware — not `SCHEDULED_ADMIN_TOKEN`, which the UI cannot send. Any caller may pause; `resume` is principal-only (`is_principal_or_self`, 403 otherwise; open while no principal is rostered; a header-less caller resolves to the principal as in `chat`), and status carries `can_resume` for the viewer so the UI hides Resume from everyone else. |\n| `workspace` | `GET /workspace`, `PUT /workspace` | Solo/team mode, the user's time zone and the principal's role (`memory.workspace_settings`). Both return `{mode, timezone, effective_timezone, role_kind, role_title, reports_to, remit, measured_on, company_domains, company_domains_custom}` — `timezone` is what the user set (null when unset), `effective_timezone` the zone in effect (`timezone`, else `USER_TIMEZONE`, else UTC), and each role field is null until set. `PUT` is a partial update: only the fields sent change; `mode` is `solo` or `team` (not null), `timezone` an IANA zone, or null/blank to clear it; `role_kind` is `owner`, `in_house`, `independent` or `other`, and `role_title` / `reports_to` / `remit` / `measured_on` are free text (trimmed, at most 120 / 120 / 500 / 300 characters), each null or blank to clear it; an unknown zone, a bad mode or role kind, an over-long role field or an unknown field is a 422 and changes nothing. Switching to solo cancels every pending department check-in, switching to team re-schedules them, and a new zone re-times the pending briefs and reflection; a role change has no side effects (the next turn reads it). `company_domains` is the company's own email domains (a teammate matches by local part on them — see Org): `GET` returns the ones in effect (the stored list, or the domain of the principal's primary address, with `company_domains_custom` false) only to the same caller the role is shown to, `[]` for anyone else; `PUT` takes a list (at most 10 plain domain names, never a free-mail provider's — 422 otherwise, the value never quoted) or null / `[]` to go back to deriving them, and a change is audited with the new list. Each change writes a `workspace_settings_changed` audit row (a role change adds `details.role_fields_changed`, the names of the fields that changed — never their text). The role is the principal's: `GET` returns it only to a caller `PUT` would accept and reads it as nulls for anyone else. `PUT` is the principal's alone (`is_principal_or_self`, 403 otherwise; a header-less caller resolves to the principal as in `chat`) and open while no principal is rostered, so first-run setup can pick a mode. Both work before onboarding — unlike `company-profile`, nothing here needs a profile. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). `DELETE /scheduled/{id}` cancels a `pending` row (409 otherwise). Like pause it only stops work, so any signed-in user may — the UI proxy's `x-caller-email` is trusted when the request also carries the `BACKEND_SHARED_SECRET` `x-api-key` — as may a matching `X-Admin-Token` (`SCHEDULED_ADMIN_TOKEN`) or a loopback caller with no token set; otherwise 401 (token set) or 503. Audited as `scheduled_action_cancelled`. |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom`, `GET\\|DELETE /workflows/custom/{name}/targets`, `POST /workflows/runs/{run_id}/decision`, `POST /workflows/runs/{run_id}/rerun`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. `rerun` queues a failed scheduled run (a department check-in, a saved workflow on a cadence) once more, due now (see Scheduler); the principal may, and for a saved workflow the person it delivers to; 409 for a run that did not fail, one started from `/jobs` (\"Start this one again from its page\") or one already queued again. Custom definitions come back with a server-managed `owner_person_id` (the creator — the web caller on `POST`, set on insert only; a client-sent value is ignored), who is asked to approve a workflow's first write to a new target. `GET /workflows/custom/{name}/targets` lists the targets its tool steps may write to without asking and `DELETE …/targets?value=` forgets one. `POST /workflows/{name}/runs` is a 403 (\"Only the principal can run this workflow.\"), audited, before any run row exists, when the workflow is one only the principal may start in the workspace's mode (`weekly_review` always, `morning_brief` in solo) and the caller is not the principal. A request with no `x-caller-email` counts as the principal; with no principal on the roster, no signed-in caller does. This governs starting a run only. A run started by hand (this endpoint, or `run_workflow` / research in chat) records its starter as `owner_person_id` and is theirs alone: `GET /workflows/runs` lists the team's (scheduled, no owner) runs plus the caller's own and the ones waiting on them, and `GET` / `DELETE /workflows/runs/{run_id}` and `POST /workflows/runs/{run_id}/decision` are a 404 for anyone else's, the principal included. A signed-in email that is on nobody's People entry cannot start one (403), and a run whose starter can't be read is refused (503); its steps read and draft documents as the starter only. `POST /workflows/runs/{run_id}/decision` with `{decision: \"approve\"|\"reject\"}` answers a run awaiting a yes/no sign-off from the web app — 403 unless the caller is the person it waits on or the principal, 409 if it isn't awaiting or needs a written reply — through the same `apply_resolution` a chat reply uses. Custom create/update also rejects (422) any action-step tool that does not resolve, and so does `POST /workflows/custom/{name}/activate` when turning a workflow **on** — that click is the approval for a tool workflow chat saved switched off (turning off is never checked). Turning on a workflow with action steps requires the body `{is_active: true, definition}` carrying the definition the user reviewed; if the stored one differs (ignoring `is_active` and timestamps) it returns 409, and the switch itself is a compare-and-set on the validated revision (`dynamic_store.activate_if_unchanged`, keyed on `updated_at`), so a save that lands while the tool check awaits the gateway — even from another process — is a 409 too, so only what was shown gets switched on. `GET /workflows/custom` lists inactive definitions too; `GET /workflows/{name}` 404s for them. The two `tools` endpoints return `{tools: [{name, description, read_only, source}]}` for the advanced editor's tool picker and the review card; `read_only` is true only when the name says it reads (a label, not a control). The run stream adds a `progress` event (`step_id`, `summary`) while an action step uses tools. Each catalog entry (`WorkflowMeta`) carries `is_custom`, `background` (true for the system-run built-ins the UI files under “System”) and `quick` (true for a Quick workflow, one per playbook nothing else follows, named `quick_<playbook>`). The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`, so that `awaiting_human` frame carries `terminal: true` to say so explicitly, plus `resumable` — whether the run continues by itself once answered or stops at the gate. `GET /workflows/runs/{run_id}` returns the run row with the resume payload replaced by a small `resume_progress` summary (`gate_step_id`, `completed_step_ids`, or `null`): the payload holds every completed step's full text, and the run-detail page polls this endpoint while a run is unfinished. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\n| `skills` | `/skills`, `/skills/search`, `/skills/{name}/restore` | Skill registry (the UI's **Playbooks**) CRUD and search. `PUT` on a built-in saves a company customization that shadows it; `DELETE` returns `{name, outcome}` — `deleted`, `reverted` (customization removed, built-in back) or `hidden` (built-in hidden for this company); `restore` un-hides; `GET /skills?include_hidden=true` lists hidden built-ins. List and detail carry `used_by` — `[{name, title, is_custom}]` of the workflows that follow the playbook (switched-off custom ones included) (`WorkflowMeta.playbooks` is the other direction). |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. `POST /evals/runs` is a 403 when a workflow scenario names a workflow that only the principal may start in the mode it runs in (the weekly review; the morning brief in solo) and the caller is not the principal — the Jobs page's rule for starting a run; stored results are read under the existing `/evals/runs` rules. |\n| `memories` | `/memories/{decisions,initiatives,advice}`, `GET /memories/facts`, `POST /memories/facts/{fact_id}/{retire,approve,decline}`, `GET /memories/facts/approval`, `PUT /memories/facts/approval/{person_id}`, `GET /memories/people`, `GET /memories/people/{person_id}/conclusions` | Episodic-memory record management; the standing facts the Pulse Corrections tab reads (`{facts: [...], can_retire, retirable_ids, can_review}`; each fact carries `recorded_by_role` / `recorded_by_name`; `?include_inactive=` default true, honoured for the principal only; anyone else gets the active rows plus their own `proposed` ones, with the provenance (`session_id`, `turn_id`, `recorded_by_person_id`, `retired_reason`, and `source_quote` except on their own facts) blanked, never retired, replaced or declined text; `?limit=` 1–500) and their retire (the principal any fact, a teammate only one they recorded that the principal has not approved — else 403; the audit row names the teammate; 404 for an unknown or `profile` row, 409 when no longer active; writes a private `fact_retired` audit row); approve / decline a teammate's `proposed` fact (principal only, else 403; 409 when it is not proposed; private `fact_reviewed` row); and the per-teammate \"needs my approval\" switch (on by default; `GET` lists `[{person_id, full_name, needs_approval}]` for every active team member but the principal, `true` for anyone not yet set; `PUT` takes `{needs_approval}`, 404 for anyone else; both principal only; private `fact_approval_changed` row); plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5) and one person's full conclusion list, paged newest first (`{status, person_id, items, page, size, total, has_more}`; `?page=` ≥1, `?size=` 1–100, default 50; 404 when the person has no peer). Peer memory is each person's own: the overview holds only the caller's entry (none for a caller off the roster; `conclusion_total` counts only theirs), the principal included, and `/conclusions` for anyone but the caller is a 404. |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/understand`, `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/revise`, `/onboard/interview/{id}` (GET resumes, DELETE starts over), `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). `revise` changes one earlier answer (0 = the description) and runs the interview again from there. `commit` answers 403 when the draft would make a different person the owner and the caller is not the current owner (setup demotes the old principal, and any signed-in user can open it). It also takes an optional `owner_email` — the principal's sign-in email, which the review screen pre-fills from the signed-in user — checked before anything is written (422 if it is malformed, already another person's, or would replace the principal's existing email — setup only fills in a missing one; 403 if the caller is not the owner and it is not the address they signed in with, since the roster is the sign-in allow-list) and saved on the principal's People row, so the owner's chats resolve to them from the first turn. |\n| `workflow_designer` | `POST /workflows/designer/start`, `POST /workflows/designer/edit`, `POST /workflows/designer/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard, and editing a saved workflow by conversation. `/edit` (`{name}`) opens a session on a saved custom workflow with no model call: the stored definition is the starting draft, and every response then carries `editing` (its name) and `original` (the stored definition as the session opened on it); drafts keep that name and its on/off state whatever the model writes (404 for an unknown workflow). The UI saves one with `POST /workflows/custom/{name}/save-edit` (`{session_id, definition}`): the server saves the session's own draft, never a client-sent body, and only when it equals the `definition` the user reviewed (a later message is a 409, so the click saves only what was shown); it re-validates it, keeps the stored on/off state, and writes only if the stored workflow is still the version the conversation opened on — otherwise 409, as it is for a session about another workflow or one with nothing drafted yet. It sits under `/workflows/custom` so anything that limits writes to custom workflows covers it too. The `workflow_designer` agent asks clarifying questions (`phase: \"question\"`, with `hint` and up to four suggested `options`), then returns `phase: \"draft\"` with `draft.definition` (exactly the body `POST /workflows/custom` takes), `summary`, and `assumptions`; every response carries the `transcript`. **Nothing is persisted here** — sessions are in memory, and the UI saves through `POST /workflows/custom`. Errors are fixed strings (422 over the 8,000-char message cap or the transcript cap, 404 for an expired session, 409 while another turn on the same session is still running, 502/504 for model failure or timeout). Mounted ahead of the `workflows` router. |\n| `python_jobs` | `GET /python-jobs/{job_id}/{name}` | A result file a Python job (`run_python_job`) wrote, the principal's alone (403 otherwise), served as a download (`Content-Disposition: attachment`, `Content-Security-Policy: sandbox`, `nosniff`, `Cache-Control: no-store`); 404 for a bad id or name or a file past its 7 days. |\n| `saved_tools` | `GET /saved-tools`, `GET\\|PUT /saved-tools/{name}`, `POST /saved-tools/{name}/rollback` | The scripts the Executive saved as tools (Settings → Advanced → Saved tools), the owner's alone (403 otherwise). The list gives each tool's name, description, on/off, current version, `kind` (`script` or `python`, a kept Python job) and the tools it calls, plus whether `SAVED_TOOLS_ENABLED` is on; the detail adds the script, every version and the last 20 runs. `PUT {enabled?, workflows?, version?}` turns one on or off (off also turns it off for workflows, so turning it back on never re-arms unattended runs), and turns the named `version` — the one the owner looked at, never whatever is current by then — on for workflows (or workflows off); a Python tool never turns on for workflows (409) — turning workflows on lets more run unattended, so it needs a request tied to the owner (signed sign-ins or local login, as Take the lead's switches do; 409 otherwise); `rollback {version}` makes that version the one that runs. Both are audited as `saved_tool_changed`. The Executive saves tools itself through `run_script`; there is no create route. |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. Its final answer saves the profile and adds people with their emails and a principal, so once there is an owner only they can send it (403, and the session rolls back so the owner can still finish it). `/onboard/start` reads the workspace mode once for the session: solo skips the Team Size, Team Members and Fractional Executives steps. Each status response's `current_step` / `total_steps` count only the steps that session asks, and `optional` says whether the current step can be skipped. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `alerts` (private cards) | `POST /alerts/{id}/ack`, `/reopen`, `/alerts/bulk-ack` | An alert tagged `private:principal` (see Today) is a 404 on ack and reopen for anyone but the principal, and their bulk sweep skips it. A roster-request card (source `roster_request`) is a 409 on `ack` even for the principal — it is answered at `/people/requests/{id}`, since acking would leave the sender waiting with nothing to show it — and, as an exempt source, `bulk-ack` and `reopen` skip it. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived **team members** with an email, offered to the UI's sign-in gate — a contact is never on it, so adding a client to reach them by email no longer lets them sign in. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. With local login (`make dev` with Google sign-in not set up — the UI then listens on 127.0.0.1 only) the UI signs in without an email, sends no `x-caller-email`, and the backend resolves the caller to the principal, as it does for the CLI. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. `POST /fixtures/reset` leaves no departments, like a new install (`departments_seeded` is always 0). |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat`, `POST /webhook/slack` | Inbound integration callbacks (self-verified). `/webhook/slack` answers 503 unless `SLACK_SIGNING_SECRET` is set. |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools, answered as the verified caller (`api.caller`) by the web app's rules. See the MCP Server section. |\n\n**What it may do** (`api/routes/may_do.py`): `GET /what-it-may-do` is read-only. It returns `{paused, sections}`, three sections in order (`as_you`, `executive`, `departments`), each `{key, title, available, unavailable, notes, rows, footer, goes}`, and each row `{id, what, outcome, then, why, setting, items}`: `outcome` is `goes`, `waits`, `always_waits`, `drafts` or `off`, and `setting` names where to change it (`act_as_me`, `handle_it`, `take_the_lead`, `pause`, `department:<slug>`, or empty). `as_you` is the caller's own (`available` false, with why, when they can't have Act as me); `executive` is the principal's alone (`available` false for anyone else); `departments` is everyone's. Any team member on People may call it; a contact, someone not on People, or a request with no caller outside local login gets 403. See Delegation → What it may do.\n\n**How far it goes as you** (`api/routes/delegation.py`): `PUT /delegation/reach` takes `{step}`, one of `off`, `when_asked`, `inbox`, `careful`, `balanced`, `bold`, `everything`, and answers the caller's delegation state as `GET /delegation` does. Going down turns the switches above the step off, highest first; going up runs each switch's own route in order (`PUT /delegation`, `PUT /delegation/inbox`, `PUT /delegation/handle-it`, `PUT /delegation/take-the-lead`), so the first refusal (409 `gmail_not_connected`, a signed sign-in missing, `in_training`, 403 for Everything when not the owner) stops it at a whole step. See Delegation → How far it goes as you.\n\n**Take the lead** (`api/routes/take_the_lead.py`): `GET /take-the-lead` returns the As the Executive switch, its six Ask first switches (`{kind, label, hint, on}`, the hint a plain line on what each one catches), the company's rules, whether this server can tie a change to the owner (`available`), and whether the Executive is paused. `PUT /take-the-lead` takes `{enabled?, ask_first?}`, and `POST /take-the-lead/rules` / `DELETE /take-the-lead/rules/{id}` add or remove a company rule (`{kind: person|domain|words|amount, value}`, 422 on a bad one). All four are the principal's alone (403). Anything that lets more happen on its own (turning it on, turning an Ask first off, removing a rule) needs a caller the API can tie to them (`delegation.verified.caller_refusal`, else 409). `GET /today/activity` adds `took_the_lead` rows (what Take the lead did, named, not quoted) and, for the caller alone, `sent_as_you` rows for what Handle it for me sent as them. Under `/delegation`: `PUT /delegation/take-the-lead {enabled}` is Take the lead as you (the owner's only for now; turning it on turns Handle it for me on), and `GET|POST /delegation/take-the-lead/rules` and `DELETE …/rules/{id}` manage the caller's own rules. `HandleItOut` gains `lead` and `lead_available`. A `take_the_lead_action` decision is approved or rejected through the existing `/decisions/{id}/approve|reject`. Training: the response also carries `training` (In training: everything waits unless allowed), `learned` (`{id, label, feature, example, uses, created_at}`: what it was allowed, the edit kept as an example by field) and `suggested` (`{key, label, approvals}`); `PUT` takes `training?` too, and leaving training while on needs the same provable owner as turning it on. `POST /take-the-lead/learned {key}` allows a current suggestion (404 for anything else; provable owner), `DELETE /take-the-lead/learned/{id}` makes it ask first again. `learned` also lists the owner's own Act as me senders (`feature` `act_as_me`), never anyone else's, and Remove works on those too. On a `take_the_lead_action` card, `POST /decisions/{id}/approve` takes `edits.input` (the card's editable fields, 422 for any other; the principal's alone, 403 for an area approver) and `edits.allow: true` (a training card only, 422 otherwise; the principal from a provable request, 403 otherwise), finishing `approved_with_edit` when a field changed.",+ "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). A request it lets through is marked `request.state.shared_secret_ok`, which is what lets an MCP request turn on \"may act\" with `x-mcp-client-actions: on` (`mcp_server.may_act`; with no secret the header is ignored and `MCP_CLIENT_ACTIONS` decides). With local login (`OE_LOCAL_LOGIN=1`, which only `make dev` sets, and only while neither Google nor SSO sign-in is set up) a second middleware answers 403 to any request whose raw `Host` is not `localhost`, `127.0.0.1` or `[::1]` (except a webhook that verifies its caller: Google Chat and Slack always, Telegram only with a `TELEGRAM_WEBHOOK_SECRET` Telegram can send), and to any write whose `Sec-Fetch-Site` is present and not `same-origin`/`none`. The UI signs that owner in with no password and this API usually has no secret, so without it a web page in the owner's browser could drive the API as the principal — by DNS-rebinding its own hostname to 127.0.0.1, or by posting a plain form from another site or localhost port. CORS is restricted to the UI origins in `BACKEND_ALLOWED_ORIGINS`, plus the `make dev` UI on `localhost:3000` only when `OE_PUBLIC_DEPLOYMENT` is unset, so a public instance never answers a localhost page with credentials. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\n**Who is calling** is read in one place, `api/caller.py`, which answers with a `Caller` kind and email; a test fails on any other read of an `x-caller-*` header. By default (`open`) it is the `x-caller-email` the UI proxy stamps from the sign-in, trusted because whoever holds the shared secret is trusted as the proxy, and a request with none runs as the principal. **Signed callers** remove that trust. With `CALLER_ASSERTION_PUBLIC_KEYS` set, the proxy signs every request with an Ed25519 key only the UI holds, and a third middleware checks the `x-caller-assertion` header:\n\n- **What it covers.** It is good for one method, the exact path and query, at most 120 seconds, and one use. The API keeps used ids in memory.\n- **What it names.** A `user`, by email, or the `operator`: local login, which runs as the principal.\n- **No caller header at all** is a `service`, for scripts or MCP clients holding only the secret. It is never the principal, not even on an install with no owner yet, so it can't save a first setup.\n- **Anything else is a 401.** That includes an `x-caller-email` without an assertion (`caller_assertion_required`), and a bad, expired, reused or mismatched assertion (`caller_assertion_invalid`).\n\nPublic keys that can't be read stop the boot, rather than fall back to trusting the header. `scripts/make-caller-keys.py` makes the pair, and `scripts/mint-caller-assertion.py` signs one request for curl. The API holds only public keys. Setup's API-protection check warns while a shared secret is set without them.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat`, `POST /chat/stop`, `POST /chat/add`, `POST /chat/background`, `GET /chat/voice`, `POST /chat/transcribe` | SSE stream of a live Executive turn, with a `: keepalive` comment every `CHAT_STREAM_KEEPALIVE_S` while the turn is quiet. `POST /chat/background` starts a new chat that the server answers to the end with nobody connected (a phone approving a card, then closing the app): it answers `202` with the new `session_id` once the same caller, access and quota checks as `/chat` pass, the turn saves itself as a `/chat` turn does, and one caller may have three running at once (`429` beyond that). `POST /chat/add` hands the running turn a message the person typed while it works; the turn takes it at its next step and the stream names it in a `message_added` event, and a second `POST /chat` on the same conversation waits for the first to finish. `GET /chat/voice` says whether the chat mic shows (`available`, `max_seconds`); `POST /chat/transcribe` takes one recording (multipart `file`) and answers `{text}` for the message box, nothing kept: `404` when speech to text isn't set up, `400` for a file that isn't audio, `413` over 25 MB, `502` when the speech server fails. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. Each round of tool calls also emits an `activity` event (`{type, label, tool, iteration}`) naming what is running — progress only, forwarded verbatim and never persisted with the message, unlike an `action_taken` chip. A `session_id` in the body must be a chat the caller may use (the same ownership rule as `sessions`). If it isn't, the turn runs in a fresh chat instead, so nothing is written into someone else's session and the reply looks the same as for an unknown id. An unknown namespaced id (`slack:…`, `telegram:…` and so on) is ignored and a fresh chat is started, because those ids belong to the channel adapters and claiming one first would make the caller its owner. The client mints a `client_turn_id` and sends it with the turn; `POST /chat/stop` takes that id and halts the turn mid-flight, so the button is live from the moment Send is pressed rather than only once the first SSE byte arrives. A stopped turn emits a `stopped` event and then the usual `done` over the same still-open stream — never an `error` — and whatever streamed so far is persisted and flagged. The endpoint returns 404 both for an unknown id and for another caller's turn, so it cannot be used to probe which turns are live. An optional `memory_text` (1–2000 chars) is what peer memory records as the caller's words instead of `message` — the briefing handoffs send it because their seed quotes the Executive's own card; `POST /chat/upload` derives it from the typed text and filenames. Since it never reaches the transcript, the `chat_turn` audit row keeps it beside `message`. After the reply — a stopped or timed-out one too, before the `stopped` / `error` / `done` frames — a turn that looked at anything sends one `sources` event, `{type, session_id, sources: [{kind, title, url}], unavailable: [area]}`: `kind` is `company`, `knowledge`, `notion`, `research`, `document` or `web`, `url` is only ever an http(s) link or, for an earlier document, `/artifacts/<id>`, at most 12 sources (6 from the web, pages the reply cites first), and `unavailable` names parts of the analysis (\"finance\") whose specialist failed or said nothing every time it was asked. It is persisted with the reply as `chat_messages.sources`. A request that carries `x-caller-email` marks its turn signed in (`Session.web_caller_signed_in`), which Act as me needs on a deployment without local login. |\n| `sessions` | `GET /sessions`, `GET /sessions/shared-with-me`, `GET /sessions/topics`, `PATCH\\|DELETE /sessions/topics/{topic_id}`, `POST /sessions/topics/{topic_id}/merge`, `POST /sessions/topic-areas/rename`, `POST /sessions/topic-areas/ungroup`, `GET\\|PATCH /sessions/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup`, `GET\\|PUT /sessions/{id}/shares`, `DELETE /sessions/{id}/shares/me`, `GET /sessions/{id}/people`, `GET /sessions/{id}/live`, `POST /sessions/{id}/typing`, `GET /sessions/{id}/export`, `POST /sessions/{id}/rewind` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller, and each chat carries `preview`: its last message as one plain line, Markdown marks stripped and cut at a word near 120 characters, with `You:` before the person's own words. With `?q=` it is a search: the caller's own chats whose title or message text contains the words (case-insensitive, `LIKE` with wildcards escaped), each with `match_count` (messages that contain them; 0 for a title-only match) and `snippet` (the newest matching message, around the match, prefixed `You:` or `Executive:`). Scoped exactly like the list, so nobody else's conversation can match. The Chats page searches this way and opens a result with `?find=`, so the chat starts on that message and steps through the others. Each of the owner's chats also carries `topic_id`, the topic it is filed under (`memory.chat_topics`). `GET /sessions/topics` lists the caller's topics (`id`, `name`, `chat_count`, `kept`, `pinned_at`, `area`, `updated_at`) and, when some of their chats have no topic yet or some topics no area, starts filing them in the background from their titles and answers `organizing: true` until done. `PATCH /sessions/topics/{topic_id}` renames (a name another of their topics has merges the two) or pins one, `POST …/merge` moves its chats into another (`into_id`), and `DELETE` ungroups it, leaving its chats under no topic; another person's topic is a 404. `POST /sessions/topic-areas/rename` (`area`, `name`) renames one of the caller's areas and `…/ungroup` (`area`) drops it, its topics standing alone; an area they don't have is a 404. `PATCH /sessions/{id}` also takes `topic_id` (null for none) or `topic_name` (made if new) to file the chat, which then is never refiled on its own. A chat-app conversation started with /new is left off the list until its first turn (`memory.conversations`). Every per-session route checks ownership, because session ids are guessable (`slack:dm:<user id>`, `telegram:<chat id>`): only the session's owner or the principal gets through, and a legacy row with no owner is the principal's alone. A teammate's own chat (a web chat, a DM, a private Telegram chat; not a channel or group conversation, `chat._shared_space`) is theirs alone, the principal included, as their mail with the Executive is. Anyone else gets the same 404 as for an unknown id, so the routes can't be used to find out which chats exist. The one other way in is having started the chat in this process (matched by Person id or verified email, so it survives the caller being added to the roster), which is how a caller the roster can't resolve keeps using their own chat. That record is in memory, so after a restart such an ownerless chat is refused for reads. The principal can continue someone else's ownerless chat without becoming its owner. Deleting a session also drops its in-memory copy, so a later turn naming that id starts fresh. The feedback route records 👍/👎 (`{\"feedback\": \"up\"|\"down\"|null}`) on one assistant reply; only the session's own caller or the principal may rate it. The rater is stored (`feedback_by_person_id`), and a 👎 on a reply to the rater's own message triggers a working-style pass for them (paced; see attunement). The chat stream's `done` event carries `message_id` for the persisted reply. The followup route returns `{\"suggestion\": string|null}` — one suggested next user message, written by the utility-fast model from the last few turns, that the chat composer shows as its greyed placeholder (Tab / → or the inline chip fills it in without sending). It is null unless the session ends on a persisted assistant reply, and null (uncached) when the model fails. Same ownership check as feedback; successful suggestions are cached in-process per (session, reply id). Messages from `GET /sessions/{id}/messages` carry each assistant reply's saved `sources` (the same shape as the chat stream's `sources` event, without `type`), so a reloaded chat shows them again. The owner (not the principal on someone else's chat; the principal for an ownerless one) also has the chat controls. `PATCH` takes `{title?, pinned?}`: a name they give is kept (`sessions.title_locked`, so the automatic title never replaces it) and a pinned chat lists first, newest pin first, with `pinned_at`. `PUT /sessions/{id}/shares {person_ids}` adds exactly those team members to it (not contacts, the archived or the owner: 422), audited `session_shared`; a chat that read its owner's own mail (`mail_private`) is never shared (409) and stops being open to those it was shared with before, and a chat-app conversation is never shared (409). Those added get it from `GET /sessions/shared-with-me` (with `shared_with_you`, `shared_by`, `shared_at`) and **write in it with the owner**: `POST /chat` with its id runs their turn as themselves (`chat._shared_member` widens the turn's access, never its ownership), and they may read it, its messages (without the owner's ratings) and its export. They can't rate, rename, delete, share or redo it, and `DELETE /sessions/{id}/shares/me` takes them out of it (audited `session_shared`, with them under `removed`). In a chat several people are in, messages carry `sender_person_id` and `sender_name` (a message from before it was shared is the owner's), `GET /sessions/{id}/people` returns `{you, people: [{person_id, full_name, owner}]}` (owner first; empty for a chat of one), and redo is refused (409) when the last message is someone else's. `GET /sessions/{id}/live` is a server-sent event stream each open page holds (`api.chat_live`, one in-process broker): `ready` first (with the running turn so far, if any), then `turn_started` (who sent what), the reply's `chunk` / `thinking` / `activity` / `action_taken` / `phase`, `turn_ended` (the page reads the chat again), `typing` (from `POST /sessions/{id}/typing`, at most once per 2 s per person) and `people`. `removed`, `deleted` and `resync` (a page that fell 1024 events behind) end it; the access check runs again on every 20 s keepalive. At most 12 pages per person, 40 per chat and 2000 per process (429). Archiving someone takes them out of every chat shared with them, and their open streams close at the next keepalive. The page closes it while its tab is hidden. `GET /sessions/{id}/export` returns the chat as a Markdown file (`memory.chat_export`: each message under its writer's People name or `Executive`, the reply's sources listed under it). `POST /sessions/{id}/rewind {last_message_id}` takes back the last turn for Try again and Edit: under the conversation's turn lock it deletes the last reply and the messages it answered, but only while that reply is still the chat's last row, and returns those messages' words (`{message}`), which the page sends again as an ordinary `/chat` turn through the usual gates. 409 while a turn is answering, for a stale reply id, and for a chat-app conversation (its reply also lives in Slack, Telegram or Discord); audited `session_rewound`. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/value`, `GET /today/top-three`, `GET /today/weekly-review` | Morning-brief aggregation (in the install's first week, for the principal, `first_week_card` `{needs_goal, findings: [{title, summary}], brief_tomorrow}` or null), recent-action rail, Pulse heartbeat heatmap (per-day activity counts), and the owner's month tally for Pulse's Done for you (`GET /today/value?period=month|week&offset=N`: counted lines beside the period before plus the finished reports, owner only, 403 otherwise; see Today). `GET /today` carries the viewer's cached \"What's going on\" `narrative` with `narrative_generated_at` (when it was written) and `narrative_stale` (a fresher one is being written — the page re-polls; see Today). A proposal backed by a roster request carries `roster_request` (the new sender's server-derived details and held-message previews; the principal's only) and is answered through the `people` routes below. `brief-delivery` returns the latest morning brief or end-of-day digest that didn't reach the owner, as `{brief, at, problem, fix, readable}` in plain language (`readable` is false when it couldn't be written, so there is nothing to read), or null — null while briefs go out, once the cause is fixed, while the scheduler is off, and for anyone but the owner (`chat._caller_is_principal_or_unclaimed`); it carries no address or channel id. `top-three` and `weekly-review` feed the solo Briefing's own cards and answer only in solo mode and only to the principal (`workflows._caller_is_the_principal`: a principal match or no caller header, never an unclaimed roster); anyone else, and team mode, get null. `top-three` returns `{items: [{key, kind, text, why, slot}]}` — the morning brief's top three from the same code (`build_top_three(principal_due_soon())`), `slot` a free block like `10:00–11:00`, `\"\"` when none is left, null when no calendar was read — and is kept off `GET /today` because its calendar read may take up to 4 s. `weekly-review` returns the latest completed `weekly_review` run as `{run_id, completed_at, period, top_three, excerpt}` (next week's top three as plain text; `excerpt` when that list is empty), or null when none has completed. |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive`, `GET /people/requests`, `GET /people/requests/{id}`, `POST /people/requests/{id}/approve`, `POST /people/requests/{id}/decline`, `GET\\|POST /people/{id}/open-loops` (a `POST` tells the owner once and returns `notified`: `sent` with the channel, `held`, `not_reached` or `skipped`; see Attunement), `POST /open-loops/{loop_id}/close`, `GET /people/{id}/outreach`, `GET\\|PUT\\|DELETE /people/{id}/attunement` | Roster CRUD and scope lookups. Every `Person` carries `kind` (`team` / `contact`). `GET /people` lists team members only unless `?include_contacts=true` (the People page asks for both; the department-head and workflow pickers keep the default); `POST` / `PATCH` accept `kind`, and a principal contact is a 422 either way. They also take `email_aliases` (other addresses the person writes from, at most 10; on `PATCH` the full list replaces the current one, omitted leaves it): an alias matches their mail and may be emailed but never signs in; a malformed one is a 422, and an alias — or a new primary `email` — that is already someone else's address or alias is a 409. Every `POST` / `PATCH` then closes any pending roster request whose sender now matches someone and replays its held messages. Adding, editing and archiving (`POST`, `PATCH`, `/archive`) are the principal's only, or anyone's while no one is principal yet so a first setup can add its owner (`chat._caller_is_principal_or_unclaimed`, the check behind `PUT /workspace`; a request with no `x-caller-email`, such as the CLI or local login, counts as the principal). Anyone else, a person editing their own row included, gets 403 before the person lookup, so it can't probe which ids exist. Contacts are private to the principal (`caller_is_principal`: the signed-in email is the principal's, or no `x-caller-email`; stricter than the owner rule above, so while no one is principal nobody is): for anyone else `include_contacts` is ignored, a contact's id is a 404 on `GET /people/{id}` and open-loops (exactly as for a missing id; `PATCH` and archive are already a 403 for them), and creating a contact or turning someone into one is a 403, even on a first setup with no principal yet. `GET /people/me` returns `{person_id, is_principal}` so the UI offers contacts to the principal only. `GET /people/by-scope/{token}` never returns a contact. Archiving a person closes their open loops. The open-loop routes list what a person owes (soonest due first) and close one (`reason`: done / not_needed / cancelled) — both the principal's or the owner's only (403 otherwise, via `people.store.is_principal_or_self`). `POST /people/{id}/open-loops` `{task, due_date?}` assigns that person a task (201 with the loop; `due_date` is a local date, due 17:00 in the user's timezone, clamped to 60 days, default 2 days): any active team member may assign anyone on the team, 403 for anyone else; 409 for an archived person, a contact (as seen by the principal), a person at the open-loop cap, a duplicate or open loops turned off; 422 for an empty task. Nobody is messaged at assignment — the owner is chased once it is due. `/outreach` returns, per kind of proactive outreach over 30 days, `sent` / `replied` / `acted` / `ignored` / `pending` (voided DMs are excluded) — same access rule, checked before the person lookup so it can't probe which ids exist. `/attunement` reads, replaces (`rules`: up to 4 strings, or omitted to only set `locked`) or resets the person's working-style rules — same access rule, 404 for an archived person; `PUT` rejects a rule that is not purely about style with 422. Archiving a person also drops their working style and frees their aliases. The **roster-request** routes (declared before `/people/{person_id}`) are the principal's alone (`caller_is_principal`; anyone else gets 404, as for a missing id): `GET /people/requests?status=pending|approved|linked|declined|expired|superseded|all` lists up to 100 (`id`, `channel`, `channel_ref`, sanitised `display_name`, `profile_email`, `on_company_domain`, `suggested_kind`, `suggested_person_id` / `_name`, `status`, `resolved_person_id` / `_kind`, `message_count`, timestamps, `ack_sent`, and `previews` of the held messages while pending — shown to the principal, never to a model); `approve` takes either `link_person_id` (+ `replace_channel_id`) or `full_name` + `kind` (no default: 422 without both) + optional `role`; `decline` takes no body. An answered request is a 409, a chat id or address already on someone else is a 409; the held messages are replayed (or dropped) in the background. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals`, `POST /goals` | Department state and per-department goals. `POST /goals` takes a goal plus `area` (a name, ≤80): an existing area by slug or title, else a new one of that name (no specialist, as with `POST /departments`), else **General** when blank; the Goals page uses it while a workspace has no areas (setup makes none for solo or a team that names none). `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. A `cadences` spec that does not parse is rejected with a 422 (empty means no cadence, i.e. the check-in is off); a changed `check_in` cancels the pending check-in and queues the next one on the new schedule. `GET` and `PATCH /departments/{slug}` return the department state plus `next_check_in_at` (ISO UTC of the pending check-in, `null` when it is off, the workspace is solo or none is queued); the list route does not carry it. A new `head_person_id` must be a team member: an unknown id and one of the principal's contacts get the same name-free 422 (`person_id N is not on the team.`), so the route — open to any signed-in user — never reveals that a contact exists; an unchanged head is not re-checked. `POST .../goals` requires only `key_result`: a missing or blank `period_value` is filled with the current period for `period_type` in the user's zone (the same label `create_goal` uses), and `target` defaults to empty. `PATCH .../goals/{id}` rejects a blank `key_result` or `period_value` with a 422; `target` may be cleared. |\n| `agents` | `GET /agents`, `GET /agents/models`, `GET /agents/models/options`, `GET /agents/presets`, `POST /agents/presets/{id}`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. `/agents/models` is the flat model allowlist the PATCH validator uses; `/agents/models/options` returns the same ids in the same order, each tagged with `provider`, `provider_label`, `route` (`direct` / `openrouter` / `local`) and a display `label`, for the Council's Provider → Model picker. `AgentDetail` carries `instructions` (additional instructions, appended after `prompt`, which stays the built-in prompt or its replacement); `PATCH` and `/test` accept `instructions` (max 4,000 chars, blank clears it). `GET /agents/presets` lists the Fast, Balanced and Thorough quality presets (each with `available` and the resolved `model` for this install) plus `active` (null when the council is Custom), `base` and `custom_agents`; `POST /agents/presets/{id}` applies one by writing per-agent model and deep-reasoning overrides and returns the same shape (404 unknown preset, 409 when the install allows none of its models). Each `AgentMeta` carries `visibility` (`core` or `internal`) so the Council's simple view can list core agents first. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/approve`, `GET /alerts/approvals/{id}`, `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/snooze`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `approve` (body `{edited_body?}`, 202) carries a proposal card out on the server and records who approved it and when (`alerts.approvals`, see Today): it queues the scheduled action a department-gated card held, or runs one Executive turn as the approver in a new chat (`session_id`). 409 for a card already approved or closed, a decision-backed card (approved at `/decisions`), a roster request or a drafted artifact; 403 unless the caller is the card's routed person or the principal (an unrouted card is the principal's); 429 when the caller already has three background turns running. `GET /alerts/approvals/{id}` reads one back (`running`, then `done` / `failed` with `outcome`) for its approver, the card's person or the principal (404 for anyone else). `snooze` (`until`, an ISO time up to 30 days ahead; `null` clears it, the Undo) hides an `unread` card until then by setting `snoozed_until` (409 on a closed card or a roster request); the TTL then counts from the snooze, so a card snoozed past its TTL still comes back. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `GET /artifacts/{id}`, `GET /artifacts/{id}/download?as=`, `POST /artifacts/{id}/archive`, `POST /artifacts/{id}/restore`, `DELETE /artifacts/{id}` | Browsable deliverables in any format — Markdown, HTML, Word, Excel, or a link into a connected app — with `format`, `downloads`, `external_url`, `supersedes_id` and, for an extension's kind of document, `collection` / `collection_label` on every summary (`orchestrator.extensions`; archive, restore and delete tell the collection first and answer 502 if it refuses). `download` renders the file (Word/Excel built at request time from the stored text; any Markdown artifact, workflow output included, can export `?as=docx`) and is always an attachment with `nosniff` and a sandbox CSP. Every route answers for the signed-in caller (`artifact_records.Viewer`): a drafted artifact is its owner's alone (`alerts.owner_person_id`, the person whose conversation published it; none = the principal's), a workflow output follows its run (`persistence.run_visible_to`), and anything the caller may not see is a 404 like a missing id, the principal included. `POST /alerts/{id}/ack` and `/reopen` answer 404 for someone else's drafted artifact the same way. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET`/`PUT /decisions/classes/meeting_scheduling`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). What approve/reject/cancel do is per class (`DECISION_CLASSES`, one `DecisionClassSpec` each; meeting booking books on approve and deletes on cancel; `delegation_reply`, an inbox reply card, is its approver's alone (`approver_only`) — hidden from everyone else, the principal included when it is a team member's — sends its Gmail draft on approve and, after a reject, deletes the draft unless it was edited; `department_action`, a team member's chat send or edit their department held (see Org), is the principal's and its approver's alone (`principal_and_approver`), makes that exact call on approve and audits `department_action_done` / `_failed` / `_declined`), and an instance of a class with no spec gets 409 instead of being carried out as another. Only the principal, or the person the decision went to for approval (`approver_person_id`), may approve, reject or cancel it. Anyone else gets 403, and a decision nobody was asked about, or one private to the principal, is the principal's alone. The resolver is recorded as `resolver_person_id`, and a reject that loses the race to another answer is a 409. `GET /audit/reliability` is the principal's alone (403 otherwise), because it counts private decisions too. A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. An approval whose caller resolves to the principal runs the booking inside `grant_contact_egress()`, so a meeting the principal proposed with a contact can be created. Such a booking's payload is marked `private`: it is proposed to the principal, left out of anyone else's `GET /decisions`, and a 404 for them on `GET /decisions/{id}` and every action route. Reviewed in the briefing — there is no separate proposals page. The class routes read and set how meetings are handled: both return `{decision_class: \"meeting_scheduling\", mode: \"propose\" \\| \"auto_execute\"}` (default `propose`); the `PUT` body is `{mode}`, principal-only (403 otherwise, open before a principal exists — but then only `propose` can be set: `auto_execute` is a 409 until a non-archived principal is on the roster), 422 on any other mode, and a change writes a `decision_class_mode_changed` audit row. In solo mode the class mode decides a booking, and `auto_execute` applies only to a turn the principal started on a verified surface — any other turn gets a proposal. |\n| `delegation` | `GET`/`PUT /delegation`, `GET`/`PUT`/`DELETE /delegation/voice`, `POST /delegation/voice/learn`, `POST /delegation/voice/describe`, `POST /delegation/voice/signature`, `PUT /delegation/inbox`, `POST /delegation/inbox/check`, `GET /delegation/replies`, `PUT /delegation/replies/{id}/text`, `GET /delegation/actions`, `PUT /delegation/handle-it`, `PUT /delegation/disclosure`, `PUT /delegation/training`, `DELETE /delegation/learned/{id}`, `GET /delegation/handled`, `PUT /delegation/team` | Act as me — the **caller's own** delegation only; nobody sets it for anyone else. It answers the principal, and a team member once the owner lets them; anyone else gets 403 `not_available_yet`. `GET /delegation` returns `{enabled, gmail: {status, message, email, connect_command, outlook_connect_command, provider}, inbox: {enabled, status, message, watch_since, last_poll_at, checking}, handle_it: {enabled, mode, available, sent_today, lead, lead_available}, training: {replies, follow_ups, actions, drafts, learned}, disclosure: {enabled, handle_it, approved_sends, line}, team}`, where `team` is the owner's switch for the principal while `DELEGATION_TEAM_MEMBERS` allows it — `{enabled, members: [{person_id, name, enabled, inbox, drafts_30d, sent_30d}]}`, counts only — and `null` otherwise. `PUT /delegation/handle-it` takes `{enabled?, mode?}` (`mode` is `careful`, `balanced` or `bold`; anything else is a 422 `bad_mode`) from a caller the API knows is that person — 403 `not_yours`, 409 `caller_signing_required` with only the shared secret — and turning it on needs Act as me and Draft replies to my inbox on (409 `act_as_me_off` / `inbox_off`); `GET /delegation/handled` returns `{replies: [{decision_id, sent_at, to_name, to_email, subject, body, open_questions, gmail_link, source}]}`, the caller's replies and follow-ups (`source` `follow_up`) sent on its own in the last 7 days; a card on `GET /delegation/replies` carries `source` the same way, `can_allow` while Replies (Follow-ups, on a follow-up) is in training, and `learns_style` while Drafts is. `PUT /delegation/disclosure` takes `{handle_it?, approved_sends?}` (any other field is a 422), the caller's own switches for the AI line on replies sent as them (`disclosure.enabled` is the install's `AI_DISCLOSURE`); turning one on needs no signed sign-in, turning one off does (409 `caller_signing_required`), and a change is audited as `delegation_disclosure_changed`. `PUT /delegation/training` takes `{replies?, follow_ups?, actions?, drafts?}` (any other field is a 422) and returns the `GET /delegation` shape; putting Replies or Follow-ups in, or Suggested actions out, needs no signed sign-in, anything else does (409 `caller_signing_required`), and putting Replies or Follow-ups in turns Take the lead as you off (`PUT /delegation/take-the-lead` on answers 409 `in_training` while they are). `training.learned` is `[{id, label, setting, example, uses, created_at}]`, what the caller allowed or kept in training (`setting` `replies`, `follow_ups`, `actions` or `drafts`; the kept example, or \"\"); `DELETE /delegation/learned/{id}` removes one of the caller's own (404 for anyone else's). `PUT /delegation/team` takes `{enabled}` from the principal alone (403 `principal_only`; 409 `not_available` when the install doesn't allow it). The Gmail `status` is `connected`, `not_configured`, `needs_reconnect`, `mismatch`, `no_email`, `shared_mailbox` or `error`, checked live with Google on each call. `PUT` takes `{enabled}` (any other field is a 422); turning it on needs the caller's own Gmail connected, otherwise a 409 whose code says why (`gmail_not_connected`, `gmail_needs_reconnect`, `gmail_mismatch`, `no_email`, `shared_mailbox`, `gmail_error`). The voice routes show, learn (from the caller's sent mail, one pass at a time — a 409 `in_progress`, `locked`, `too_soon`, `not_enough_mail`, `no_profile` or `changed` when it was locked or edited while learning, or a Gmail code), write it from the caller's own description (`POST /delegation/voice/describe` with `{description}`: one model call applies their words to the profile they have and returns it with a short `sample_reply`, saving nothing, so they review it and save it with `PUT`; a 409 `empty`, `too_long`, `in_progress`, `too_many` past 10 an hour or `no_profile`; no mailbox needed), edit and lock, and reset \"How I write\": a typed field that fails validation is a 422 `invalid_voice` listing each `rejected` field, and `clear_exemplars` / `clear_signature` drop those. `POST /delegation/voice/signature` reads the signature from the caller's Gmail settings again and changes nothing else (a locked profile stays locked), with the same Gmail codes as learning: a 409 when their mailbox isn't connected, it refuses the sign-in or the check itself fails (`gmail_error`), and a 502 `gmail_error` when reading the signature fails. On an Outlook mailbox it is a 409 `signature_unavailable`, since Outlook gives apps no signature to read, and the stored one is left alone. A caller `can_delegate` refuses — anyone but the principal, for now — gets 403 `not_available_yet`, which hides the Settings card. A request with no `x-caller-email` is a 403 `sign_in_required` unless the API runs under local login — a header-less call is not a sign-in (the caller is read through `api/caller.py`, as on every principal-only route). `PUT /delegation/inbox` takes `{enabled}` and turns **Draft replies to my inbox** on or off, returning the same shape as `GET /delegation`: on needs Act as me on (409 `act_as_me_off`) and the mailbox connected (the Gmail codes above, which keep their names for an Outlook mailbox too), and turning Act as me off turns it off too. `POST /delegation/inbox/check` starts a scan now in the background and answers 202 with the `inbox` state (409 `inbox_off` or `in_progress`). `GET /delegation/replies` returns `{cards: [...]}`, the caller's open reply cards from the database alone (no Gmail call): the decision id, the sender's name, address, relation and whether it was verified, the subject, when it arrived, what they wrote, the draft's recipients, subject and body, `open_questions`, `flags` and a Gmail link built from a fixed prefix. **Send** is `POST /decisions/{id}/approve`: it sends the card's draft exactly as it is in Gmail, after checking again that the caller is its owner — which on a server needs signed callers (409 `caller_signing_required` otherwise) — that both switches are on (`inbox_off`), no client slot is active (`client_slot`), the Gmail is connected (the Gmail codes), the draft is still there and unanswered (`draft_gone`, `you_replied`) and its recipients are allowed (`no_recipients`, `too_many_recipients`, `executive_recipient`, `not_from_you`). Recipients that changed, or a newer message in the thread, answer 409 `{code: \"confirm\", message, reasons, recipients}`; approving again with `edits: {recipients: <the list shown>, thread_moved_on: true}` is the second yes. **Send + allow** adds `edits.allow: true`: 422 `cant_allow` unless Replies (Follow-ups, on a follow-up card) is in training, 409 `learned_full` when their list is full, both before anything is sent; `edits.example: true` keeps a draft edited in the mailbox as how they write to that person while Drafts is in training. A draft edited in Gmail between those checks and the send is not sent (`draft_changed`). A double tap sends once (`already_handled`); Gmail refusing answers 429 `rate_limited` or 502 `gmail_error` with nothing sent, and a send Gmail didn't confirm answers 502 `send_unconfirmed` and is settled by the next inbox scan. Dismiss is `POST /decisions/{id}/reject`. `GET /delegation/actions` returns `{cards: [...]}`, the caller's own approval cards (`delegation_actions`): the decision id, when it was made, a one-line `why`, and each action's `index`, `kind` (`invite`, `message`, `add_contact`), `summary` and `text` (a message as it will be sent, or a meeting's description). **Approve** is `POST /decisions/{id}/approve` with `edits: {only: [indexes]}` (and `allow: true` for Approve + allow while Suggested actions is in training: 422 `cant_allow` otherwise or when nothing on it can be allowed, 409 `learned_full`; a card carries `can_allow`); it needs the card's own person signed in (403 `not_yours`, 409 `caller_signing_required`), Act as me on (409 `act_as_me_off`) and a card under a week old (409 `expired`), runs once (409 `already_handled`), and returns the decision with `final_payload_json.results`: per action `done`, `waiting` (sent to whoever approves meetings), `failed` with why, or `skipped`. Every change writes a private audit row. |\n| `history` | `GET /memories/history` (`?q=`), `PUT /memories/history/settings`, `PATCH`/`DELETE /memories/history/{id}`, `POST /memories/history/{id}/forget-conversation` | Always in the loop: the **caller's own** notes and switches only, resolved as for Act as me (a signed-in person on the roster, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{notes, reply_notes, retention_days, effective_retention_days, company_retention_days, retention_choices, can_keep_notes, can_note_replies, can_set_company_retention, share_work_style, can_share_work_style}` (`can_keep_notes`: a team member on the People list may turn notes on; `can_note_replies`: they can use Act as me, so email replies are noted too; `share_work_style`: their own \"Share my work style with the team\" switch, `can_share_work_style`: a team member in a team workspace). `PUT` turns notes on only for someone who may keep them, and `share_work_style` on only for someone who may share it (403 `not_available` for either; turning either off always works), takes a person's retention only when shorter than the company's (422 `invalid_setting`), and the company retention only from the principal (403 `principal_only`). `PATCH` pins or corrects a note; `DELETE` forgets it; `forget-conversation` is \"Don't remember this\". A note that isn't the caller's is 404. Every change is audited privately to its person. |\n| `reflection` | `GET /memories/reflection` (`?person_id=`), `DELETE /memories/reflection/misses/{id}` | What it got wrong: the turns the conversation review graded a miss (`memory.chat_review`), with the person's words, the reply, the tools run, what they wanted instead, the `kind` (`company` / `product`) and the signals, plus `weeks` (`{week, graded, misses}` per ISO week, newest first) and `sees_everyone`. The caller is resolved as for `history` (403 `sign_in_required` / `not_on_roster`); each person sees their own, the principal those from chats `chat._session_access` lets them open (a teammate's own web chat or DM and a mail-private conversation stay their owner's; channels and groups are open), or one person's with `?person_id=` (a teammate naming someone else gets 403 `not_yours`); the weekly counts carry no words and are not filtered. The same response carries `lessons` (`memory/lessons.py`: live first, then retired, each with `shown`/`fine_after`/`miss_after` and `retired_reason`), filtered by the same rule, and `DELETE /memories/reflection/lessons/{id}` retires one (204; 404 for a lesson the caller may not see, already retired, or missing). `DELETE` forgets one miss (`is_principal_or_self`; 404 `not_found` otherwise) and writes a `chat_review` audit row. Each miss also carries its nightly replay (`memory/replay.py`): `replay_state` (`open` / `closed` / `evidence`), `replayed_at`, `closed_at`, `replay_notes`; and the response carries `replay` (`{misses, would_pass, evidence, last_run_at}`: of the caller's visible misses from the last 30 days, how many would go right today). |\n| `notifications` | `GET /notifications/settings`, `PUT /notifications/settings` | Settings → Notifications: the **caller's own** settings only, resolved as for the notes (a signed-in person on the People list, or the principal under local login; otherwise 403 `sign_in_required` / `not_on_roster`). `GET` returns `{quiet_hours: {enabled, start, end, days}, delivery, urgent_through, timezone, effective_timezone, held_count, gets_briefs, updated_at}` — `days` is `every_day` or `weekdays`, `delivery` `instant` or `digest`, `timezone` the zone they chose (`\"\"` for the workspace's), `held_count` how many messages wait for their quiet hours or brief (counted, never listed), `gets_briefs` whether they are the principal. `PUT` takes `{quiet_hours, delivery, urgent_through, timezone}` and replaces them (extra fields, equal start and end, a bad time or an unknown zone → 422); switching `digest` → `instant` makes what waited for the brief go now. Audited as `notification_settings_changed`. See Org. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts), plus `scripts`: how many `run_script` scripts ran (and worked, and in workflows), the tool calls they made, their time, and `turns_avoided` — an upper bound on the model turns those calls would otherwise have needed (each call past a script's first) — and `python_jobs`: how many Python jobs ran (and worked, ran a kept Custom tool, took a chat attachment), their time, CPU, largest peak memory and bytes in and out, and the tokens and charge of the turns that ran one. The Token usage page shows it as a Scripts section. Rows private to the principal (`private_to_principal`: a turn about their private mail, or a row naming one of their contacts on their own turn) are theirs alone: for any other caller, resolved as for `/alerts`, the usage totals leave them out. Once a principal is on the roster, anyone else reads only their own rows (a teammate's own turns, their Act as me work) in the list, by id and in a session, and the principal reads those as actions only — what was done, when and in whose conversation, with the text, details and `full` left out, and no text search over them; any other row's id is a 404, and a session shows only the rows the caller reads. |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes. Only `/health` is unauthenticated; `/health/honcho` sits behind the gate like everything else, because the exemption is an exact-path set. `/health` also carries `google_tools_missing`, the pinned Google tools startup priming could not find: `[]` once it has checked and they are all there, a list of names when a workspace-mcp rename or the configured services and tool tier left one out, and `null` for no answer — Google Workspace is not configured, or the probe has not finished or it failed. Only `[]` asserts they are present. It also carries `gateway`, the MCP gateway's state from its supervisor (`orchestrator.gateway_boot`): `state` is `off` (MCP not enabled), `no_servers` (enabled, the config names none), `starting` (an attempt is running), `up` or `down` (every attempt so far failed; `next_retry_at` is the next one), with `attempts`, `up_since` and `email_poller` (whether the poller that rides on the gateway runs); the failure's own text stays out, since the route is open to anyone, and goes to the log and the owner's notice on Home. A hosted instance whose gateway never came up used to answer `ok` here with no email going out or in. Only `[]` asserts the tools are present, so a probe that died cannot read as healthy; Setup status says which of the three `null` means. |\n| `version` | `GET /version` | The running version, the latest release on GitHub and `update_available`, for Settings → About. The GitHub answer is cached 6h, only a semver `tag_name` is used and the release link is built from it; `UPDATE_CHECK_ENABLED=false` skips the call and still returns the running version. No in-app updater: upgrading is host-side (`docs/deployment.md#upgrading`). |\n| `setup_status` | `GET /setup/status` | Settings → Setup status: one light per part of the install — AI model, company setup, owner, the Executive's address, API protection, Gmail, your own mailbox (Act as me), Slack, Discord, Telegram, Google Chat, the scheduler, the daily brief (when and where it goes) and Honcho — as `{checked_at, checks: [{id, label, state, summary, fix, link, last_activity}]}`, where `state` is `ok`, `warn`, `error` or `off` (optional and not set up), `fix` says what to do in plain language, `link` is an in-app page that helps (`/people`, `/onboard`) and `last_activity` is the channel's latest `integration_inbound` audit time. It tests live, with at most one free read-only call per service, each bounded to 5 s: Anthropic `models.list` (so an organisation key missing `ANTHROPIC_WORKSPACE_ID` shows up), Slack `auth.test`, Telegram `getMe` and `getWebhookInfo`, Discord `users/@me` only while the bot is still connecting, and — once the owner's own Gmail credential exists — Google's token refresh and Gmail `users/me/profile`. It also reads the listeners the lifespan leaves on `app.state` (Slack's socket, the Discord bot and its task, the MCP gateway), the scheduler heartbeat and the pause switch. When `google_workspace` is configured, the lifespan also starts `MCPGateway.prime_pinned_tools()` in the background (held on `app.state.mcp_prime_task`, cancelled at shutdown), so the pinned Google tools named in the prompt are callable without a search. With `DRIVE_SYNC_ENABLED` the lifespan also bootstraps the `drive_sync_scan` heartbeat beside Notion's (see Scheduler); the Drive folder sync has no HTTP route, only the `openexecutive sync-drive` / `purge-drive` CLI. With `CONFLUENCE_SYNC_ENABLED` it bootstraps the `confluence_sync_scan` heartbeat the same way; that sync is run by hand with `openexecutive sync-confluence` / `purge-confluence`. Sample values copied from `.env.example` are named as such without being sent anywhere. No token reaches a response or a log line: probes report a status code, a service's short error code or an exception's class name. Requests within 5 s of a run get that run's answer and concurrent requests share one run (kept per app on `app.state`), so the button can't become a stream of calls to those services. Gated like every other route; the UI adds a sign-in light of its own, from its own settings. |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}`, `GET /documents/sources`, `POST /documents/sources/{drive\\|onedrive\\|notion}/sync`, `GET /documents/{drive\\|onedrive\\|notion}`, `GET /documents/{drive\\|onedrive\\|notion}/{id}` | Upload, list, view extracted text, and delete indexed company docs. `GET /documents` rows carry `source: \"upload\"` and the `domain` the upload was indexed under. The connected-source routes back the knowledge page's single Company documents list: `/documents/sources` gives each source's `{id, label, enabled, syncing, last_run, last_error, interval_minutes, file_count}`; `/documents/drive`, `/documents/onedrive` and `/documents/notion` list synced files from the sync state (`{enabled, last_run, last_error, files: [{id, name, url, modified_at, synced_at, indexed}]}`; a Drive row also carries `unreadable_reason`, why a file with `indexed: false` has no text — e.g. a scan OCR could not read — or null); `/documents/{drive\\|onedrive\\|notion}/{id}` returns the stored text (a OneDrive id is `<drive id>:<item id>`) for an id on record (the path comes from the state, never the caller). They are read-only — a synced file is removed where it lives. `POST …/sync` starts one tick of the same sync the scheduler runs as a background task (202); 409 when the source is not connected or a tick is already running (every sync holds a per-process run lock, so a manual run never overlaps the heartbeat; the route also keeps its own started task per source and re-checks just before starting one, so two simultaneous requests start one tick, not two), 429 with `Retry-After` within 60 s of the last successful run or of the end of the last tick in this process, failed ones included, so a failing or slow source can't be re-run back-to-back. The page's text view never loads images from synced content (a remote image would be a read beacon for whoever edits the shared folder). Upload is keyed on the filename, so re-uploading a document replaces its chunks rather than duplicating them, and `DELETE` removes the rows as well as the file. `domain` must be one of the nine specialist domains (including `sales`) or `general`; anything else is a 400 rather than a 200 that indexes where no specialist can retrieve. A scanned PDF is converted (`knowledge.pdf_reader`) before it is indexed and in the text view, as are scanned PDFs in `POST /chat/upload` and the client / onboarding intake uploads. The upload is streamed to disk 1 MB at a time and refused with a 413 once it passes 50 MB, and the file is parsed in a short-lived child process (see the RAG section), so a large document does not stay in the API process's memory. A Word or Excel file that cannot be parsed, or whose parse runs out of time, is a 422 with a readable reason. When every parser is busy, the response is a 503 with `Retry-After`. |\n| `executive` | `GET /executive/status`, `POST /executive/pause`, `POST /executive/resume` | Operator pause switch for all autonomous work (scheduler, Gmail poller, workflow resumer); inbound chat and DMs stay live. Status returns `{paused, paused_at, paused_by, reason, held_actions, can_resume, name}` — `held_actions` counts due `pending` rows that fire on resume, and `name` is the Executive's name (`EXEC_DISPLAY_NAME`), which the web chat shows over its replies. `pause` takes an optional `reason` (≤200 chars) and is idempotent (re-pausing keeps the original start and reason); `paused_by` is the UI proxy's `x-caller-email`, else `api`. Behind the shared-secret middleware — not `SCHEDULED_ADMIN_TOKEN`, which the UI cannot send. Any caller may pause; `resume` is principal-only (`is_principal_or_self`, 403 otherwise; open while no principal is rostered; a header-less caller resolves to the principal as in `chat`), and status carries `can_resume` for the viewer so the UI hides Resume from everyone else. |\n| `workspace` | `GET /workspace`, `PUT /workspace` | Solo/team mode, the user's time zone and the principal's role (`memory.workspace_settings`). Both return `{mode, timezone, effective_timezone, role_kind, role_title, reports_to, remit, measured_on, company_domains, company_domains_custom}` — `timezone` is what the user set (null when unset), `effective_timezone` the zone in effect (`timezone`, else `USER_TIMEZONE`, else UTC), and each role field is null until set. `PUT` is a partial update: only the fields sent change; `mode` is `solo` or `team` (not null), `timezone` an IANA zone, or null/blank to clear it; `role_kind` is `owner`, `in_house`, `independent` or `other`, and `role_title` / `reports_to` / `remit` / `measured_on` are free text (trimmed, at most 120 / 120 / 500 / 300 characters), each null or blank to clear it; an unknown zone, a bad mode or role kind, an over-long role field or an unknown field is a 422 and changes nothing. Switching to solo cancels every pending department check-in, switching to team re-schedules them, and a new zone re-times the pending briefs and reflection; a role change has no side effects (the next turn reads it). `company_domains` is the company's own email domains (a teammate matches by local part on them — see Org): `GET` returns the ones in effect (the stored list, or the domain of the principal's primary address, with `company_domains_custom` false) only to the same caller the role is shown to, `[]` for anyone else; `PUT` takes a list (at most 10 plain domain names, never a free-mail provider's — 422 otherwise, the value never quoted) or null / `[]` to go back to deriving them, and a change is audited with the new list. Each change writes a `workspace_settings_changed` audit row (a role change adds `details.role_fields_changed`, the names of the fields that changed — never their text). The role is the principal's: `GET` returns it only to a caller `PUT` would accept and reads it as nulls for anyone else. `PUT` is the principal's alone (`is_principal_or_self`, 403 otherwise; a header-less caller resolves to the principal as in `chat`) and open while no principal is rostered, so first-run setup can pick a mode. Both work before onboarding — unlike `company-profile`, nothing here needs a profile. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). `DELETE /scheduled/{id}` cancels a `pending` row (409 otherwise). Like pause it only stops work, so any signed-in user may — the UI proxy's `x-caller-email` is trusted when the request also carries the `BACKEND_SHARED_SECRET` `x-api-key` — as may a matching `X-Admin-Token` (`SCHEDULED_ADMIN_TOKEN`) or a loopback caller with no token set; otherwise 401 (token set) or 503. Audited as `scheduled_action_cancelled`. |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom`, `GET\\|DELETE /workflows/custom/{name}/targets`, `POST /workflows/runs/{run_id}/decision`, `POST /workflows/runs/{run_id}/rerun`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. `rerun` queues a failed scheduled run (a department check-in, a saved workflow on a cadence) once more, due now (see Scheduler); the principal may, and for a saved workflow the person it delivers to; 409 for a run that did not fail, one started from `/jobs` (\"Start this one again from its page\") or one already queued again. Custom definitions come back with a server-managed `owner_person_id` (the creator — the web caller on `POST`, set on insert only; a client-sent value is ignored), who is asked to approve a workflow's first write to a new target. `GET /workflows/custom/{name}/targets` lists the targets its tool steps may write to without asking and `DELETE …/targets?value=` forgets one. `POST /workflows/{name}/runs` is a 403 (\"Only the principal can run this workflow.\"), audited, before any run row exists, when the workflow is one only the principal may start in the workspace's mode (`weekly_review` always, `morning_brief` in solo) and the caller is not the principal. A request with no `x-caller-email` counts as the principal; with no principal on the roster, no signed-in caller does. This governs starting a run only. A run started by hand (this endpoint, or `run_workflow` / research in chat) records its starter as `owner_person_id` and is theirs alone: `GET /workflows/runs` lists the team's (scheduled, no owner) runs plus the caller's own and the ones waiting on them, and `GET` / `DELETE /workflows/runs/{run_id}` and `POST /workflows/runs/{run_id}/decision` are a 404 for anyone else's, the principal included. A signed-in email that is on nobody's People entry cannot start one (403), and a run whose starter can't be read is refused (503); its steps read and draft documents as the starter only. `POST /workflows/runs/{run_id}/decision` with `{decision: \"approve\"|\"reject\"}` answers a run awaiting a yes/no sign-off from the web app — 403 unless the caller is the person it waits on or the principal, 409 if it isn't awaiting or needs a written reply — through the same `apply_resolution` a chat reply uses. Custom create/update also rejects (422) any action-step tool that does not resolve, and so does `POST /workflows/custom/{name}/activate` when turning a workflow **on** — that click is the approval for a tool workflow chat saved switched off (turning off is never checked). Turning on a workflow with action steps requires the body `{is_active: true, definition}` carrying the definition the user reviewed; if the stored one differs (ignoring `is_active` and timestamps) it returns 409, and the switch itself is a compare-and-set on the validated revision (`dynamic_store.activate_if_unchanged`, keyed on `updated_at`), so a save that lands while the tool check awaits the gateway — even from another process — is a 409 too, so only what was shown gets switched on. `GET /workflows/custom` lists inactive definitions too; `GET /workflows/{name}` 404s for them. The two `tools` endpoints return `{tools: [{name, description, read_only, source}]}` for the advanced editor's tool picker and the review card; `read_only` is true only when the name says it reads (a label, not a control). The run stream adds a `progress` event (`step_id`, `summary`) while an action step uses tools. Each catalog entry (`WorkflowMeta`) carries `is_custom`, `background` (true for the system-run built-ins the UI files under “System”) and `quick` (true for a Quick workflow, one per playbook nothing else follows, named `quick_<playbook>`). The run endpoint streams SSE; its `awaiting_human` event carries `delivery` (`self` \\| `sent` \\| `suppressed` \\| `alerted` \\| `failed`) alongside `person_id` / `question` / `awaiting_until`, because the outbound guard or an unreachable approver means the question may never have been asked — a client must not render “waiting on them” for those. A paused run ends the stream with neither `done` nor `error`, so that `awaiting_human` frame carries `terminal: true` to say so explicitly, plus `resumable` — whether the run continues by itself once answered or stops at the gate. `GET /workflows/runs/{run_id}` returns the run row with the resume payload replaced by a small `resume_progress` summary (`gate_step_id`, `completed_step_ids`, or `null`): the payload holds every completed step's full text, and the run-detail page polls this endpoint while a run is unfinished. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. `/search` is the introspection parallel of `retriever.retrieve` and mirrors its filters — including the `general` catch-all on the company collection — so the panel cannot report a specialist seeing nothing that it does retrieve in chat. It accepts `general` in `domain_filter` for the same reason. `/search` applies the same review gate as `retrieve()` — withheld (pending or rejected) built-in, external and failure rows are dropped, so the panel never advertises knowledge the Executive cannot use; it degrades to unfiltered rather than failing if review state is unreadable. `POST /knowledge/builtin` refuses a name already held by shipped content, and `POST|DELETE /knowledge/failures` now register and deregister for review — without that a user-authored failure case study had no review row, so no SME decision could block it. |\n| `skills` | `/skills`, `/skills/search`, `/skills/{name}/restore` | Skill registry (the UI's **Playbooks**) CRUD and search. `PUT` on a built-in saves a company customization that shadows it; `DELETE` returns `{name, outcome}` — `deleted`, `reverted` (customization removed, built-in back) or `hidden` (built-in hidden for this company); `restore` un-hides; `GET /skills?include_hidden=true` lists hidden built-ins. List and detail carry `used_by` — `[{name, title, is_custom}]` of the workflows that follow the playbook (switched-off custom ones included) (`WorkflowMeta.playbooks` is the other direction). |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. `POST /evals/runs` is a 403 when a workflow scenario names a workflow that only the principal may start in the mode it runs in (the weekly review; the morning brief in solo) and the caller is not the principal — the Jobs page's rule for starting a run; stored results are read under the existing `/evals/runs` rules. |\n| `memories` | `/memories/{decisions,initiatives,advice}`, `GET /memories/facts`, `POST /memories/facts/{fact_id}/{retire,approve,decline}`, `GET /memories/facts/approval`, `PUT /memories/facts/approval/{person_id}`, `GET /memories/people`, `GET /memories/people/{person_id}/conclusions` | Episodic-memory record management; the standing facts the Pulse Corrections tab reads (`{facts: [...], can_retire, retirable_ids, can_review}`; each fact carries `recorded_by_role` / `recorded_by_name`; `?include_inactive=` default true, honoured for the principal only; anyone else gets the active rows plus their own `proposed` ones, with the provenance (`session_id`, `turn_id`, `recorded_by_person_id`, `retired_reason`, and `source_quote` except on their own facts) blanked, never retired, replaced or declined text; `?limit=` 1–500) and their retire (the principal any fact, a teammate only one they recorded that the principal has not approved — else 403; the audit row names the teammate; 404 for an unknown or `profile` row, 409 when no longer active; writes a private `fact_retired` audit row); approve / decline a teammate's `proposed` fact (principal only, else 403; 409 when it is not proposed; private `fact_reviewed` row); and the per-teammate \"needs my approval\" switch (on by default; `GET` lists `[{person_id, full_name, needs_approval}]` for every active team member but the principal, `true` for anyone not yet set; `PUT` takes `{needs_approval}`, 404 for anyone else; both principal only; private `fact_approval_changed` row); plus the read-only peer-memory overview the Pulse People tab reads (`{status: ok|disabled|error, people: [...], conclusion_total}`; `?recent=` 1–50, default 5) and one person's full conclusion list, paged newest first (`{status, person_id, items, page, size, total, has_more}`; `?page=` ≥1, `?size=` 1–100, default 50; 404 when the person has no peer). Peer memory is each person's own: the overview holds only the caller's entry (none for a caller off the roster; `conclusion_total` counts only theirs), the principal included, and `/conclusions` for anyone but the caller is a 404. |\n| `review` | `/review/items`, `/review/stats`, `/review/trusted-defaults`, `POST /review/curate`, `POST /review/bulk-approve` | Knowledge review queue and annotations. Shipped knowledge registers as a trusted default (`approved` with a NULL `reviewed_at`), so the queue starts empty; `curate` (`{domain, action: start|stop}`, domain required) opts one domain in or out, and `trusted-defaults` returns domain → unreviewed count. `bulk-approve` takes a non-empty `domain`, `item_ids` (max 500) or `all_pending: true`, and 400s with no selector; it returns `{approved_count, item_ids}`. |\n| `onboarding` | `/onboard/interview/understand`, `/onboard/interview/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/revise`, `/onboard/interview/{id}` (GET resumes, DELETE starts over), `/onboard/interview/commit` | Conversational company setup. The `onboarding_interviewer` agent asks clarifying questions, then emits a draft profile + people + departments. **Nothing is persisted until `POST /onboard/interview/commit`** — the interview itself never writes. `start` is multipart (description + optional deck/one-pager uploads). `revise` changes one earlier answer (0 = the description) and runs the interview again from there. `commit` answers 403 when the draft would make a different person the owner and the caller is not the current owner (setup demotes the old principal, and any signed-in user can open it). It also takes an optional `owner_email` — the principal's sign-in email, which the review screen pre-fills from the signed-in user — checked before anything is written (422 if it is malformed, already another person's, or would replace the principal's existing email — setup only fills in a missing one; 403 if the caller is not the owner and it is not the address they signed in with, since the roster is the sign-in allow-list) and saved on the principal's People row, so the owner's chats resolve to them from the first turn. |\n| `workflow_designer` | `POST /workflows/designer/start`, `POST /workflows/designer/edit`, `POST /workflows/designer/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard, and editing a saved workflow by conversation. `/edit` (`{name}`) opens a session on a saved custom workflow with no model call: the stored definition is the starting draft, and every response then carries `editing` (its name) and `original` (the stored definition as the session opened on it); drafts keep that name and its on/off state whatever the model writes (404 for an unknown workflow). The UI saves one with `POST /workflows/custom/{name}/save-edit` (`{session_id, definition}`): the server saves the session's own draft, never a client-sent body, and only when it equals the `definition` the user reviewed (a later message is a 409, so the click saves only what was shown); it re-validates it, keeps the stored on/off state, and writes only if the stored workflow is still the version the conversation opened on — otherwise 409, as it is for a session about another workflow or one with nothing drafted yet. It sits under `/workflows/custom` so anything that limits writes to custom workflows covers it too. The `workflow_designer` agent asks clarifying questions (`phase: \"question\"`, with `hint` and up to four suggested `options`), then returns `phase: \"draft\"` with `draft.definition` (exactly the body `POST /workflows/custom` takes), `summary`, and `assumptions`; every response carries the `transcript`. **Nothing is persisted here** — sessions are in memory, and the UI saves through `POST /workflows/custom`. Errors are fixed strings (422 over the 8,000-char message cap or the transcript cap, 404 for an expired session, 409 while another turn on the same session is still running, 502/504 for model failure or timeout). Mounted ahead of the `workflows` router. |\n| `python_jobs` | `GET /python-jobs/{job_id}/{name}` | A result file a Python job (`run_python_job`) wrote, the principal's alone (403 otherwise), served as a download (`Content-Disposition: attachment`, `Content-Security-Policy: sandbox`, `nosniff`, `Cache-Control: no-store`); 404 for a bad id or name or a file past its 7 days. |\n| `saved_tools` | `GET /saved-tools`, `GET\\|PUT /saved-tools/{name}`, `POST /saved-tools/{name}/rollback` | The scripts the Executive saved as tools (Settings → Advanced → Saved tools), the owner's alone (403 otherwise). The list gives each tool's name, description, on/off, current version, `kind` (`script` or `python`, a kept Python job) and the tools it calls, plus whether `SAVED_TOOLS_ENABLED` is on; the detail adds the script, every version and the last 20 runs. `PUT {enabled?, workflows?, version?}` turns one on or off (off also turns it off for workflows, so turning it back on never re-arms unattended runs), and turns the named `version` — the one the owner looked at, never whatever is current by then — on for workflows (or workflows off); a Python tool never turns on for workflows (409) — turning workflows on lets more run unattended, so it needs a request tied to the owner (signed sign-ins or local login, as Take the lead's switches do; 409 otherwise); `rollback {version}` makes that version the one that runs. Both are audited as `saved_tool_changed`. The Executive saves tools itself through `run_script`; there is no create route. |\n| `onboarding` (fallback) | `/onboard/start`, `/onboard/answer`, `/onboard/status/{id}` | The original 12-step form wizard, kept as a fallback (UI at `/onboard?mode=form`) and used by the `openexecutive onboard` CLI. Its final answer saves the profile and adds people with their emails and a principal, so once there is an owner only they can send it (403, and the session rolls back so the owner can still finish it). `/onboard/start` reads the workspace mode once for the session: solo skips the Team Size, Team Members and Fractional Executives steps. Each status response's `current_step` / `total_steps` count only the steps that session asks, and `optional` says whether the current step can be skipped. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `alerts` (private cards) | `POST /alerts/{id}/ack`, `/reopen`, `/alerts/bulk-ack` | An alert tagged `private:principal` (see Today) is a 404 on ack and reopen for anyone but the principal, and their bulk sweep skips it. A roster-request card (source `roster_request`) is a 409 on `ack` even for the principal — it is answered at `/people/requests/{id}`, since acking would leave the sender waiting with nothing to show it — and, as an exempt source, `bulk-ack` and `reopen` skip it. |\n| `auth` | `GET /auth/allowed-emails` | Non-archived **team members** with an email, offered to the UI's sign-in gate — a contact is never on it, so adding a client to reach them by email no longer lets them sign in. The gate takes the **union** of this roster and its own `ALLOWED_EMAILS` env list, so env entries always work (and are checked first, short-circuiting the fetch) and roster entries are additive — a roster change can never revoke a configured operator. With local login (`make dev` with Google sign-in not set up — the UI then listens on 127.0.0.1 only) the UI signs in without an email, sends no `x-caller-email`, and the backend resolves the caller to the principal, as it does for the CLI. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. `POST /fixtures/reset` leaves no departments, like a new install (`departments_seeded` is always 0). |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat`, `POST /webhook/slack` | Inbound integration callbacks (self-verified). `/webhook/slack` answers 503 unless `SLACK_SIGNING_SECRET` is set. |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools, answered as the verified caller (`api.caller`) by the web app's rules. See the MCP Server section. | A card the Executive left for something asked in chat (`app_action`, `orchestrator/app_control.py`) is its person's alone too: its payload holds `action`, `id`, `value`, `title` and the `card` line shown; **Confirm** is `POST /decisions/{id}/approve`, which runs the action through the route its button calls with that request (a refusal comes back as that route's status and words, and the card is marked `failed`), and a card older than a day is turned down with 409.\n\n**What it may do** (`api/routes/may_do.py`): `GET /what-it-may-do` is read-only. It returns `{paused, sections}`, three sections in order (`as_you`, `executive`, `departments`), each `{key, title, available, unavailable, notes, rows, footer, goes}`, and each row `{id, what, outcome, then, why, setting, items}`: `outcome` is `goes`, `waits`, `always_waits`, `drafts` or `off`, and `setting` names where to change it (`act_as_me`, `handle_it`, `take_the_lead`, `pause`, `department:<slug>`, or empty). `as_you` is the caller's own (`available` false, with why, when they can't have Act as me); `executive` is the principal's alone (`available` false for anyone else); `departments` is everyone's. Any team member on People may call it; a contact, someone not on People, or a request with no caller outside local login gets 403. See Delegation → What it may do.\n\n**How far it goes as you** (`api/routes/delegation.py`): `PUT /delegation/reach` takes `{step}`, one of `off`, `when_asked`, `inbox`, `careful`, `balanced`, `bold`, `everything`, and answers the caller's delegation state as `GET /delegation` does. Going down turns the switches above the step off, highest first; going up runs each switch's own route in order (`PUT /delegation`, `PUT /delegation/inbox`, `PUT /delegation/handle-it`, `PUT /delegation/take-the-lead`), so the first refusal (409 `gmail_not_connected`, a signed sign-in missing, `in_training`, 403 for Everything when not the owner) stops it at a whole step. See Delegation → How far it goes as you.\n\n**Take the lead** (`api/routes/take_the_lead.py`): `GET /take-the-lead` returns the As the Executive switch, its six Ask first switches (`{kind, label, hint, on}`, the hint a plain line on what each one catches), the company's rules, whether this server can tie a change to the owner (`available`), and whether the Executive is paused. `PUT /take-the-lead` takes `{enabled?, ask_first?}`, and `POST /take-the-lead/rules` / `DELETE /take-the-lead/rules/{id}` add or remove a company rule (`{kind: person|domain|words|amount, value}`, 422 on a bad one). All four are the principal's alone (403). Anything that lets more happen on its own (turning it on, turning an Ask first off, removing a rule) needs a caller the API can tie to them (`delegation.verified.caller_refusal`, else 409). `GET /today/activity` adds `took_the_lead` rows (what Take the lead did, named, not quoted) and, for the caller alone, `sent_as_you` rows for what Handle it for me sent as them. Under `/delegation`: `PUT /delegation/take-the-lead {enabled}` is Take the lead as you (the owner's only for now; turning it on turns Handle it for me on), and `GET|POST /delegation/take-the-lead/rules` and `DELETE …/rules/{id}` manage the caller's own rules. `HandleItOut` gains `lead` and `lead_available`. A `take_the_lead_action` decision is approved or rejected through the existing `/decisions/{id}/approve|reject`. Training: the response also carries `training` (In training: everything waits unless allowed), `learned` (`{id, label, feature, example, uses, created_at}`: what it was allowed, the edit kept as an example by field) and `suggested` (`{key, label, approvals}`); `PUT` takes `training?` too, and leaving training while on needs the same provable owner as turning it on. `POST /take-the-lead/learned {key}` allows a current suggestion (404 for anything else; provable owner), `DELETE /take-the-lead/learned/{id}` makes it ask first again. `learned` also lists the owner's own Act as me senders (`feature` `act_as_me`), never anyone else's, and Remove works on those too. On a `take_the_lead_action` card, `POST /decisions/{id}/approve` takes `edits.input` (the card's editable fields, 422 for any other; the principal's alone, 403 for an area approver) and `edits.allow: true` (a training card only, 422 otherwise; the principal from a provable request, 403 otherwise), finishing `approved_with_edit` when a field changed.","mermaid": null,- "generated_at": "2026-10-17T22:00:00Z"+ "generated_at": "2026-10-18T19:37:35Z"}diff --git a/packages/core/openexecutive/delegation/lockdown.py b/packages/core/openexecutive/delegation/lockdown.pyindex 40c49ffa..1520e29e 100644--- a/packages/core/openexecutive/delegation/lockdown.py+++ b/packages/core/openexecutive/delegation/lockdown.py@@ -126,6 +126,11 @@ MAIL_TOUCHED_ALLOWED_TOOLS: frozenset[str] = frozenset({# Only PRIVATE_TURN_MCP_TOOLS: reads, and sends whose every recipient the# gateway checks (mail_touched_withholds)."call_tool",+ # App control (orchestrator/app_control.py): after a mail read every+ # action is a card the speaker taps; the list and the links stay in the app.+ "do_in_app",+ "find_in_app",+ "open_in_app",})MAIL_TOUCHED_WITHHELD_TOOLS: frozenset[str] = frozenset({diff --git a/packages/core/openexecutive/delegation/verified.py b/packages/core/openexecutive/delegation/verified.pyindex 5a892523..959b2eea 100644--- a/packages/core/openexecutive/delegation/verified.py+++ b/packages/core/openexecutive/delegation/verified.py@@ -4,6 +4,9 @@ turning Handle it for me on), kept apart so routes can check it withoutimporting the send path (``reply_send``)."""from __future__ import annotations+from collections.abc import Iterator+from contextlib import contextmanager+from contextvars import ContextVarfrom typing import AnyNOT_YOURS = "not_yours"@@ -22,6 +25,11 @@ def caller_refusal(caller: Any, email: str) -> str | None:from openexecutive.api.caller import signing_onfrom openexecutive.utils.deployment import is_local_login+ if _from_chat.get():+ # A route run from a chat turn (orchestrator.app_control): the caller+ # is the turn's speaker, not a signed request, so nothing that needs+ # one goes through. Those wait for a tap on a card instead.+ return SIGNING_REQUIREDif signing_on():if caller.kind == "user" and caller.email == email:return None@@ -35,3 +43,17 @@ def caller_refusal(caller: Any, email: str) -> str | None:return Nonereturn NOT_YOURSreturn SIGNING_REQUIRED+++_from_chat: ContextVar[bool] = ContextVar("verified_from_chat", default=False)+++@contextmanager+def from_chat() -> Iterator[None]:+ """Mark routes called inside this block as run from a chat turn, so+ ``caller_refusal`` refuses them whoever the caller names."""+ token = _from_chat.set(True)+ try:+ yield+ finally:+ _from_chat.reset(token)diff --git a/packages/core/openexecutive/guide/prebuilt/chat.json b/packages/core/openexecutive/guide/prebuilt/chat.jsonindex 69e43124..7133c1af 100644--- a/packages/core/openexecutive/guide/prebuilt/chat.json+++ b/packages/core/openexecutive/guide/prebuilt/chat.json@@ -1,7 +1,7 @@{"section_id": "chat","title": "Chat & Briefing",- "markdown": "**What it is:** Where you talk to the Executive in plain language. The app opens on **Home**, a quick read of what's happened across the company and what needs you, and you drop into a chat whenever you want to ask or decide something. Every conversation is kept on the **Chats** page.\n\n**What it does:**\n\n- Hold a natural conversation with the Executive, which quietly pulls in whichever specialists a question needs.\n- Keep every chat with its full history, so you can pick up where you left off.\n- See each reply under the Executive's name, the one it goes by in mail and chat.\n- Attach files to a message: up to 5 per message, 20 MB each (PNG, JPEG, GIF and WebP images, PDF, Word, Excel, text, Markdown, CSV). The Executive reads them for that message.\n- Talk instead of typing: click the microphone next to the message box, speak (up to 5 minutes), then click it again. What you said appears in the message box to fix and send. The microphone shows only when speech to text is set up.\n- Stop a reply while it is still coming. Whatever has been written is kept and marked *Stopped by you*. (Escape works too.)\n- Add to a reply while it works: type and send, and your message joins the answer in progress (*Sent while it works*, then *👀 Seen, taking it into this answer*).\n- Redo your last turn in a web chat: **Try again** under the last reply asks the same question again, and **Edit** under your last message lets you change it. Sending an edit replaces that message and its answer.\n- Turn on **Committee review** for a question that matters: a slower pass where reviewers challenge the draft answer before you see it.\n- Continue any item on Home straight into a chat thread, with the context already filled in.\n- Choose **Show agent activity** in the **⋯** menu at the top right to watch what's happening behind a reply: which specialists were consulted and which tools ran.\n- See what an answer drew on: click **Sources (N)** under a reply to list the documents and web pages it looked at (your own documents, the built-in knowledge and any web pages), with links where there are any.\n- Copy a reply with **Copy**, and rate it with 👍 (**Helpful**) or 👎 (**Not helpful**).\n\n**How to use:**\n\n1. Click **New chat** at the top of the sidebar (on a phone, the **+** in the middle of the bar at the bottom), or type into the **Ask your Executive anything…** box on Home. Click **Home** any time to get back.\n2. Type your question and press **Enter** to send. **Shift + Enter** starts a new line. When the box is empty, a greyed-out suggested follow-up may appear; press **Tab** or **→** to use it (on a phone, tap **Use suggestion**).\n3. To include a file, click the **+** next to the message box, choose **Attach files or photos** and pick up to 5 files. Drag-and-drop isn't supported in chat. Attachments are read for that message only. To make a document permanently available, add it on the **Knowledge** page.\n4. For a decision that matters, click the **+** next to the message box and choose **Committee review (slower, reviewed)** before sending. A **Committee review on** chip appears above the box. It stays on for each message you send until you click the chip (or choose **Turn off committee review** in the **+** menu). While it works you see *Drafting → Committee review → Revising*.\n5. Changed your mind mid-answer? Click the stop button (next to the message box while a reply is streaming) or press **Esc**.\n6. In an open chat, the **⋯** menu at the top right has **Pin** / **Unpin**, **Rename**, **Share**, **Download** and **Show agent activity**. Deleting is on the **Chats** page.\n7. If part of an answer couldn't be completed (say, the finance side), you still get the rest, with a short note under it. Ask again to fill in the missing part.\n8. When something you asked for needs your approval (a meeting the Executive set up for you to approve, or actions it suggested from your email), its card appears right under the reply: **Approve**, **Edit** (for a meeting: its title, start and end) and **Dismiss**. After **Approve** a meeting's card says *Booked. It's on your calendar.* The same card also waits under **Needs you** on Today until you answer it in either place. Saying *ok* in the chat doesn't book it; tap **Approve**. Things the Executive raises on its own come only to Today.\n\n**Chats page:** click **Chats** in the sidebar (on a phone, **Chats** in the bar at the bottom). It lists every conversation you own: web chats and the ones that came in through Slack, Telegram, Discord, Email and Google Chat. You only see your own chats here, plus the ones someone shared with you.\n\n- **Channel tabs:** **All** and **Web** are always there. A tab for Slack, Telegram, Discord, Email or Google Chat appears once you have a chat from it. Each tab shows its app's logo and its count. Every chat ends with the logo of where it came from: the Open Executive mark for web chats, the app's own logo for Slack, Telegram, Discord and Google Chat, and an envelope for Email.\n- **Groups:** chats are grouped into **Pinned**, **Today**, **Yesterday**, **Previous 7 Days**, **Previous 30 Days** and **Older** (collapsed until you click it). Each group shows 20 chats, then **Show N more**. Each row shows the title, when it was last active and how many messages it has.\n- **Date or Topic:** the **Date** / **Topic** switch at the right of the channel tabs, under the search box changes how the list is grouped, and the page remembers your choice. **Topic** groups your chats by what they are about (a hire, a customer, a project), whichever app they came from. Every new chat is filed under a topic when it gets its title. The first time you open **Topic**, your earlier chats are grouped from their titles, and the page says *Grouping your earlier chats by topic…* until that's done. **Pinned** stays at the top. A topic with only one chat, and chats with no lasting topic, go under **Other** (collapsed until you click it). Related topics sit under one **area** (one property, deal or client), each header shows the day it was last active, and an open topic shows its three newest chats with **Show more** for the rest. Topics with a chat this week are listed under **Active this week**; quieter ones fold into **Quiet for a week**, **Quiet for 2 weeks** and **Quiet for a month or more**, and a new chat brings a topic back up. Each band lists its five most recent topics, one line each, then **Show N more topics**. In **Topic**, the search box also finds topic and area names.\n- **Topic ⋯ menu:** **Rename topic**, **Merge into…** (moves its chats into another topic), **Pin topic** / **Unpin topic** and **Ungroup** (its chats stay, under **Other**). Renaming a topic to the name of another one merges them. An area's ⋯ menu has **Rename area** and **Ungroup area** (its topics stand on their own, and stay so). Only you see your topics.\n- **Search:** type in **Search titles and messages**. It searches the titles and message text of your own chats (up to 50 results). Each result shows *title match* or how many messages matched, with a snippet that highlights your words. Open a result found in its messages and the chat shows a bar with *match 1 of N* and arrows to step through the matches. Search does not cover chats shared with you.\n- **Row ⋯ menu** (your own chats): **Pin** / **Unpin**, **Rename**, **Move to topic**, **Share**, **Download** and **Delete chat**.\n - **Move to topic** files the chat under one of your topics, a new one, or **No topic**. Your choice sticks: the Executive never moves that chat again, and a topic you renamed, pinned or moved a chat into is never merged on its own.\n - **Pin** moves the chat to the **Pinned** group at the top. Only you see your pins.\n - **Rename** gives the chat a name (up to 120 characters). The automatic title never replaces a name you set.\n - **Download** saves the whole chat as a Markdown (.md) file: each message under who wrote it (the person's name or *Executive*), with each reply's sources listed under it.\n - **Delete chat** asks *Delete this chat? This cannot be undone.* Deleting removes the chat and its messages from Open Executive and ends any sharing of it. Messages in Slack, Telegram or Discord stay in those apps.\n- **New chat** at the top right starts a new web chat.\n\n**Sharing a chat:**\n\n- **Who you can share with:** team members on your **People** list. Contacts, archived people and yourself are not offered. If no one else is on your team, the panel says *There's no one else on your team to share with yet.*\n- **How:** in an open chat, choose **Share** in the **⋯** menu or the **Share** button in the bar above the conversation; on the **Chats** page, the chat's row **⋯** menu has **Share** too. The panel *Share this chat with:* says *They join the chat and can write in it with you.* and lists your team with a checkbox each. Tick the people, then click **Save**. It confirms *Shared.* Only the chat's owner can share it. There is no share link: access goes to the named people only.\n- **What they get:** they join the chat and write in it with you. It appears on their **Chats** page under **Shared with you**, with *<your name> added you* and when. They are not notified. Their row **⋯** menu has **Download** and **Leave chat**.\n- **Working in it together:** a bar above the conversation shows everyone's initials and *You and <name>* (or *You and N others*). Each person's message shows their name; your own stay on the right. The Executive sees who wrote each message and answers whoever wrote the latest. Everyone with the chat open sees a new message and the Executive's reply as it is written, and *<name> is typing…* above the message box. One turn runs at a time: while the Executive answers someone else, the box says *The Executive is answering <name>…* and Send waits. A chat left open in a background tab catches up when you come back to it.\n- **What only the owner can do:** rename, pin, rate replies (👍/👎), share, delete. **Try again** and **Edit** work only on your own last message, and not for the people you shared with. They don't see your ratings or your pin.\n- **What stays out of a shared chat:** everyone in it reads every reply, so it is not a private conversation. **Act as me** is off there, the Executive won't read anyone's own mail there, and your private items on Today (your mail, people waiting on you, new senders) are not brought into it.\n- **Sending from a shared chat:** once someone else writes in it, the Executive's next reply won't send email, message people, post to the company or a department, book or cancel meetings, set follow-ups, run or schedule workflows or change contacts, even when that reply is to the chat's owner. It says so, and the owner can ask again in their following message.\n- **Which chats can't be shared:** a chat in which the Executive read or drafted in your own mailbox (**Act as me**) stays yours alone. Saving a share on it fails with *This chat read your own mail, so it stays yours alone.* If a chat you already shared later reads your mail, it disappears from everyone's **Shared with you** list and they can no longer open it. This can't be undone. A conversation from Slack, Telegram, Discord, Email or Google Chat can't be shared: *Only a chat started here can be shared.*\n- **Leaving and removing:** someone you shared with can leave from the **Leave** button in the bar or **Leave chat** in the row menu; you can add them again. To remove people, open **Share**, untick them and click **Save** (with nobody ticked it says *Not shared with anyone.*). Someone removed, or who leaves, sees *You're no longer in this chat.* and later *This chat isn't shared with you any more.* if they open it. Archiving someone on **People** takes them out of every chat. Deleting the chat ends it for everyone (*This chat was deleted.*).\n- **Records:** each change to who is in a chat, including someone leaving, is written to the audit log.\n\n**Example prompts:**\n\n- \"Here's our Q3 board deck. What questions should I expect from the board?\" *(with the PDF attached)*\n- \"Should we raise prices 10% for new customers? I want the finance and marketing view.\" *(with Committee review on)*\n- \"What changed across the company this week that I should know about?\"\n\n*Tip: this is the front door. Almost everything else in the app is something the Executive references or acts on from here.*",+ "markdown": "**What it is:** Where you talk to the Executive in plain language. The app opens on **Home**, a quick read of what's happened across the company and what needs you, and you drop into a chat whenever you want to ask or decide something. Every conversation is kept on the **Chats** page.\n\n**What it does:**\n\n- Hold a natural conversation with the Executive, which quietly pulls in whichever specialists a question needs.\n- Keep every chat with its full history, so you can pick up where you left off.\n- See each reply under the Executive's name, the one it goes by in mail and chat.\n- Attach files to a message: up to 5 per message, 20 MB each (PNG, JPEG, GIF and WebP images, PDF, Word, Excel, text, Markdown, CSV). The Executive reads them for that message.\n- Talk instead of typing: click the microphone next to the message box, speak (up to 5 minutes), then click it again. What you said appears in the message box to fix and send. The microphone shows only when speech to text is set up.\n- Stop a reply while it is still coming. Whatever has been written is kept and marked *Stopped by you*. (Escape works too.)\n- Add to a reply while it works: type and send, and your message joins the answer in progress (*Sent while it works*, then *👀 Seen, taking it into this answer*).\n- Redo your last turn in a web chat: **Try again** under the last reply asks the same question again, and **Edit** under your last message lets you change it. Sending an edit replaces that message and its answer.\n- Turn on **Committee review** for a question that matters: a slower pass where reviewers challenge the draft answer before you see it.\n- Continue any item on Home straight into a chat thread, with the context already filled in.\n- Choose **Show agent activity** in the **⋯** menu at the top right to watch what's happening behind a reply: which specialists were consulted and which tools ran.\n- See what an answer drew on: click **Sources (N)** under a reply to list the documents and web pages it looked at (your own documents, the built-in knowledge and any web pages), with links where there are any.\n- Copy a reply with **Copy**, and rate it with 👍 (**Helpful**) or 👎 (**Not helpful**).\n- Ask it to change things in the app for you: \"pin this\", \"rename this chat Q3 plan\", \"move it to the Main Street topic\", \"archive that memo\", \"turn off Handle it for me\", \"open my notification settings\". It does what the button on that screen does. Deleting, sharing, and turning on anything that sends as you or acts on its own wait for you to tap **Confirm** on a card under the reply. Your account, sign-in and billing stay on their own screens.\n\n**How to use:**\n\n1. Click **New chat** at the top of the sidebar (on a phone, the **+** in the middle of the bar at the bottom), or type into the **Ask your Executive anything…** box on Home. Click **Home** any time to get back.\n2. Type your question and press **Enter** to send. **Shift + Enter** starts a new line. When the box is empty, a greyed-out suggested follow-up may appear; press **Tab** or **→** to use it (on a phone, tap **Use suggestion**).\n3. To include a file, click the **+** next to the message box, choose **Attach files or photos** and pick up to 5 files. Drag-and-drop isn't supported in chat. Attachments are read for that message only. To make a document permanently available, add it on the **Knowledge** page.\n4. For a decision that matters, click the **+** next to the message box and choose **Committee review (slower, reviewed)** before sending. A **Committee review on** chip appears above the box. It stays on for each message you send until you click the chip (or choose **Turn off committee review** in the **+** menu). While it works you see *Drafting → Committee review → Revising*.\n5. Changed your mind mid-answer? Click the stop button (next to the message box while a reply is streaming) or press **Esc**.\n6. In an open chat, the **⋯** menu at the top right has **Pin** / **Unpin**, **Rename**, **Share**, **Download** and **Show agent activity**. Deleting is on the **Chats** page.\n7. If part of an answer couldn't be completed (say, the finance side), you still get the rest, with a short note under it. Ask again to fill in the missing part.\n8. When something you asked for needs your approval (a meeting the Executive set up for you to approve, or actions it suggested from your email), its card appears right under the reply: **Approve**, **Edit** (for a meeting: its title, start and end) and **Dismiss**. After **Approve** a meeting's card says *Booked. It's on your calendar.* The same card also waits under **Needs you** on Today until you answer it in either place. Saying *ok* in the chat doesn't book it; tap **Approve**. Things the Executive raises on its own come only to Today.\n\n**Chats page:** click **Chats** in the sidebar (on a phone, **Chats** in the bar at the bottom). It lists every conversation you own: web chats and the ones that came in through Slack, Telegram, Discord, Email and Google Chat. You only see your own chats here, plus the ones someone shared with you.\n\n- **Channel tabs:** **All** and **Web** are always there. A tab for Slack, Telegram, Discord, Email or Google Chat appears once you have a chat from it. Each tab shows its app's logo and its count. Every chat ends with the logo of where it came from: the Open Executive mark for web chats, the app's own logo for Slack, Telegram, Discord and Google Chat, and an envelope for Email.\n- **Groups:** chats are grouped into **Pinned**, **Today**, **Yesterday**, **Previous 7 Days**, **Previous 30 Days** and **Older** (collapsed until you click it). Each group shows 20 chats, then **Show N more**. Each row shows the title, when it was last active and how many messages it has.\n- **Date or Topic:** the **Date** / **Topic** switch at the right of the channel tabs, under the search box changes how the list is grouped, and the page remembers your choice. **Topic** groups your chats by what they are about (a hire, a customer, a project), whichever app they came from. Every new chat is filed under a topic when it gets its title. The first time you open **Topic**, your earlier chats are grouped from their titles, and the page says *Grouping your earlier chats by topic…* until that's done. **Pinned** stays at the top. A topic with only one chat, and chats with no lasting topic, go under **Other** (collapsed until you click it). Related topics sit under one **area** (one property, deal or client), each header shows the day it was last active, and an open topic shows its three newest chats with **Show more** for the rest. Topics with a chat this week are listed under **Active this week**; quieter ones fold into **Quiet for a week**, **Quiet for 2 weeks** and **Quiet for a month or more**, and a new chat brings a topic back up. Each band lists its five most recent topics, one line each, then **Show N more topics**. In **Topic**, the search box also finds topic and area names.\n- **Topic ⋯ menu:** **Rename topic**, **Merge into…** (moves its chats into another topic), **Pin topic** / **Unpin topic** and **Ungroup** (its chats stay, under **Other**). Renaming a topic to the name of another one merges them. An area's ⋯ menu has **Rename area** and **Ungroup area** (its topics stand on their own, and stay so). Only you see your topics.\n- **Search:** type in **Search titles and messages**. It searches the titles and message text of your own chats (up to 50 results). Each result shows *title match* or how many messages matched, with a snippet that highlights your words. Open a result found in its messages and the chat shows a bar with *match 1 of N* and arrows to step through the matches. Search does not cover chats shared with you.\n- **Row ⋯ menu** (your own chats): **Pin** / **Unpin**, **Rename**, **Move to topic**, **Share**, **Download** and **Delete chat**.\n - **Move to topic** files the chat under one of your topics, a new one, or **No topic**. Your choice sticks: the Executive never moves that chat again, and a topic you renamed, pinned or moved a chat into is never merged on its own.\n - **Pin** moves the chat to the **Pinned** group at the top. Only you see your pins.\n - **Rename** gives the chat a name (up to 120 characters). The automatic title never replaces a name you set.\n - **Download** saves the whole chat as a Markdown (.md) file: each message under who wrote it (the person's name or *Executive*), with each reply's sources listed under it.\n - **Delete chat** asks *Delete this chat? This cannot be undone.* Deleting removes the chat and its messages from Open Executive and ends any sharing of it. Messages in Slack, Telegram or Discord stay in those apps.\n- **New chat** at the top right starts a new web chat.\n\n**Sharing a chat:**\n\n- **Who you can share with:** team members on your **People** list. Contacts, archived people and yourself are not offered. If no one else is on your team, the panel says *There's no one else on your team to share with yet.*\n- **How:** in an open chat, choose **Share** in the **⋯** menu or the **Share** button in the bar above the conversation; on the **Chats** page, the chat's row **⋯** menu has **Share** too. The panel *Share this chat with:* says *They join the chat and can write in it with you.* and lists your team with a checkbox each. Tick the people, then click **Save**. It confirms *Shared.* Only the chat's owner can share it. There is no share link: access goes to the named people only.\n- **What they get:** they join the chat and write in it with you. It appears on their **Chats** page under **Shared with you**, with *<your name> added you* and when. They are not notified. Their row **⋯** menu has **Download** and **Leave chat**.\n- **Working in it together:** a bar above the conversation shows everyone's initials and *You and <name>* (or *You and N others*). Each person's message shows their name; your own stay on the right. The Executive sees who wrote each message and answers whoever wrote the latest. Everyone with the chat open sees a new message and the Executive's reply as it is written, and *<name> is typing…* above the message box. One turn runs at a time: while the Executive answers someone else, the box says *The Executive is answering <name>…* and Send waits. A chat left open in a background tab catches up when you come back to it.\n- **What only the owner can do:** rename, pin, rate replies (👍/👎), share, delete. **Try again** and **Edit** work only on your own last message, and not for the people you shared with. They don't see your ratings or your pin.\n- **What stays out of a shared chat:** everyone in it reads every reply, so it is not a private conversation. **Act as me** is off there, the Executive won't read anyone's own mail there, and your private items on Today (your mail, people waiting on you, new senders) are not brought into it.\n- **Sending from a shared chat:** once someone else writes in it, the Executive's next reply won't send email, message people, post to the company or a department, book or cancel meetings, set follow-ups, run or schedule workflows or change contacts, even when that reply is to the chat's owner. It says so, and the owner can ask again in their following message.\n- **Which chats can't be shared:** a chat in which the Executive read or drafted in your own mailbox (**Act as me**) stays yours alone. Saving a share on it fails with *This chat read your own mail, so it stays yours alone.* If a chat you already shared later reads your mail, it disappears from everyone's **Shared with you** list and they can no longer open it. This can't be undone. A conversation from Slack, Telegram, Discord, Email or Google Chat can't be shared: *Only a chat started here can be shared.*\n- **Leaving and removing:** someone you shared with can leave from the **Leave** button in the bar or **Leave chat** in the row menu; you can add them again. To remove people, open **Share**, untick them and click **Save** (with nobody ticked it says *Not shared with anyone.*). Someone removed, or who leaves, sees *You're no longer in this chat.* and later *This chat isn't shared with you any more.* if they open it. Archiving someone on **People** takes them out of every chat. Deleting the chat ends it for everyone (*This chat was deleted.*).\n- **Records:** each change to who is in a chat, including someone leaving, is written to the audit log.\n\n**Example prompts:**\n\n- \"Here's our Q3 board deck. What questions should I expect from the board?\" *(with the PDF attached)*\n- \"Should we raise prices 10% for new customers? I want the finance and marketing view.\" *(with Committee review on)*\n- \"What changed across the company this week that I should know about?\"\n\n*Tip: this is the front door. Almost everything else in the app is something the Executive references or acts on from here.*","mermaid": null,- "generated_at": "2026-10-17T22:00:00Z"+ "generated_at": "2026-10-18T19:37:35Z"}diff --git a/packages/core/openexecutive/orchestrator/action_chips.py b/packages/core/openexecutive/orchestrator/action_chips.pyindex 28a32b13..071cc54c 100644--- a/packages/core/openexecutive/orchestrator/action_chips.py+++ b/packages/core/openexecutive/orchestrator/action_chips.py@@ -90,6 +90,10 @@ SIDE_EFFECTING_TOOLS: frozenset[str] = frozenset({"create_calendar_event","create_instant_meeting","cancel_calendar_event",+ # App control (orchestrator/app_control.py): done, or a card waiting for a+ # tap; and a link to a screen+ "do_in_app",+ "open_in_app",})@@ -214,7 +218,7 @@ def summarize_action(if (parsed is not Noneand parsed.get("status") == "waiting_for_approval"- and tool_name != "propose_actions"+ and tool_name not in ("propose_actions", "do_in_app")):# Held for someone's approval (a team member's send or change, the# department gate): nothing happened yet, so no "done" chip.@@ -530,6 +534,25 @@ def summarize_action(url = tool_input.get("url", "")payload["summary"] = f"Connected MCP server: {url}" if url else "Connected MCP server"payload["target"] = url or None+ elif tool_name == "do_in_app":+ status = (parsed or {}).get("status")+ if status == "done":+ payload["summary"] = str((parsed or {}).get("did") or "Done")+ elif status == "waiting_for_approval":+ card = str((parsed or {}).get("card") or "")+ payload["summary"] = f"Waiting for your OK: {card}" if card else "Waiting for your OK"+ # The chat shows the card itself under its message, by this id.+ decision_id = (parsed or {}).get("decision_id")+ if isinstance(decision_id, int) and not isinstance(decision_id, bool):+ payload["decision_id"] = decision_id+ else:+ return None+ elif tool_name == "open_in_app":+ link = (parsed or {}).get("link")+ if (parsed or {}).get("status") != "link" or not isinstance(link, str) or not link.startswith("/") or link.startswith("//"):+ return None+ payload["summary"] = f"Open {(parsed or {}).get('screen') or 'it'}"+ payload["link"] = linkelif tool_name == "run_workflow":wf = str(tool_input.get("workflow", "")).replace("_", " ")run_id = (parsed or {}).get("run_id")diff --git a/packages/core/openexecutive/orchestrator/activity_labels.py b/packages/core/openexecutive/orchestrator/activity_labels.pyindex a5d3de69..938f6dbd 100644--- a/packages/core/openexecutive/orchestrator/activity_labels.py+++ b/packages/core/openexecutive/orchestrator/activity_labels.py@@ -132,6 +132,9 @@ _LABELS: dict[str, str] = {"save_my_email_attachment": "Saving a file from your email…","remind_me": "Setting a reminder…","propose_actions": "Leaving you a card to approve…",+ "find_in_app": "Looking that up in the app…",+ "do_in_app": "Making that change…",+ "open_in_app": "Finding the right screen…","my_email_awaiting_reply": "Checking what's waiting on a reply…","my_email_read_before": "Finding the email you mean…","my_calendar": "Checking your calendar…",diff --git a/packages/core/openexecutive/orchestrator/app_control.py b/packages/core/openexecutive/orchestrator/app_control.pynew file mode 100644index 00000000..c52d7c86--- /dev/null+++ b/packages/core/openexecutive/orchestrator/app_control.py@@ -0,0 +1,561 @@+"""App control from chat: the Executive does what the app's own buttons do.++"Pin this", "rename it Q3 plan", "delete that chat", "turn off Handle it for+me": three tools in the ``app`` tool group (``tool_groups``) do these.++- ``find_in_app(kind, query)`` lists the things of one kind the speaker may+ act on (their chats, topics, documents, …), each with an id.+- ``do_in_app(action, id, value)`` does one action on one of them.+- ``open_in_app(screen)`` gives a link to a screen, for what chat doesn't do.++**The same code as the button.** Each action calls the API route the screen's+button calls, as a function, with a request that names the speaker+(``_as_speaker``). The route's own checks decide what this person may do: a+chat that isn't theirs is a 404 here as it is on the page. The speaker is the+one the chat surface verified (``correction_tools._speaker``); a turn with+none (an email, an unattended run) gets a refusal. Some routes check nothing+about the caller because their page is the principal's; those actions are+``principal_only``.++**What waits for a tap.** An action marked ``confirm`` (a delete, a share,+turning on something that sends as the person, anything that lets more go+on its own) is never done in the turn. It becomes a card in the chat+(decision class ``app_action``, ``api.routes.decisions``) that only the+speaker can see and answer, with the action spelled out. Their tap runs it+with their own request to ``/decisions/{id}/approve``, so a route that needs+a signed sign-in gets one, and the route checks them again then. After a turn+has read text from outside the team (``outside_content``) or the speaker's+own mail, every action waits for a tap: planted text ("delete the Q3 chat")+can't act on its own. A card left a day goes stale.++**Adding to it.** ``register_kind`` / ``register_action`` / ``register_screen``+add to the catalog (``app_control_catalog`` holds this repo's), at startup+before any turn, so each turn sees one fixed tool list. The tool definitions+are rebuilt in place, so the list holding them sees the change.+"""+from __future__ import annotations++import json+import logging+import sys+from collections.abc import Awaitable, Callable+from dataclasses import dataclass, field+from datetime import UTC, datetime, timedelta+from types import SimpleNamespace+from typing import Any++from openexecutive.delegation.verified import from_chat++logger = logging.getLogger(__name__)++FIND_IN_APP = "find_in_app"+DO_IN_APP = "do_in_app"+OPEN_IN_APP = "open_in_app"+APP_TOOL_NAMES: frozenset[str] = frozenset({FIND_IN_APP, DO_IN_APP, OPEN_IN_APP})++# The decision class a card is stored as (api.routes.decisions).+DECISION_CLASS = "app_action"+# A card not answered in this long is stale: what it named may have changed.+CARD_LIFETIME = timedelta(days=1)+# What "this" means for a chat: the conversation the person is in.+THIS = "this"++_FIND_MAX = 25+_VALUE_MAX = 300+++class Refused(Exception):+ """An action that can't be done, with what to tell the person."""+++@dataclass(frozen=True)+class Item:+ """One thing in the app the speaker may act on."""++ id: str+ title: str+ detail: str = ""+++# (request) → everything of the kind the caller may act on.+Finder = Callable[[Any], Awaitable[list[Item]]]+# (request, item id, value) → what was done, past tense ("Pinned “Q3 plan”").+# Raises Refused, or lets the route's HTTPException through.+Runner = Callable[[Any, str, str], Awaitable[str]]+# (request, item id, value) → the value to store and run with, worked out by+# the server in the turn (e.g. the alert ids shown), or Refused.+Preparer = Callable[[Any, str, str], Awaitable[str]]+++@dataclass(frozen=True)+class Kind:+ name: str+ # What the person calls one, e.g. "chat".+ label: str+ find: Finder+ principal_only: bool = False+ # Items of this kind need no id (a new department, the alert board).+ no_item: bool = False+++@dataclass(frozen=True)+class Action:+ name: str+ kind: str+ # What it does, for the tool description: "Pin a chat to the top of the list".+ does: str+ run: Runner+ # Whether it waits for a tap: always, or per (item id, value).+ confirm: bool | Callable[[str, str], bool] = False+ # What ``value`` is, when the action takes one.+ value: str | None = None+ # The card's line, with {title} (quoted) and {value}: "Delete the chat {title}".+ card: str = ""+ principal_only: bool = False+ prepare: Preparer | None = None++ def needs_tap(self, item_id: str, value: str) -> bool:+ return self.confirm(item_id, value) if callable(self.confirm) else bool(self.confirm)+++@dataclass+class _Catalog:+ kinds: dict[str, Kind] = field(default_factory=dict)+ actions: dict[str, Action] = field(default_factory=dict)+ # name → (app path, what it is)+ screens: dict[str, tuple[str, str]] = field(default_factory=dict)+++CATALOG = _Catalog()+++# --------------------------------------------------------------------------- #+# Tool definitions (rebuilt in place as the catalog grows)+# --------------------------------------------------------------------------- #++FIND_IN_APP_TOOL: dict[str, Any] = {"name": FIND_IN_APP}+DO_IN_APP_TOOL: dict[str, Any] = {"name": DO_IN_APP}+OPEN_IN_APP_TOOL: dict[str, Any] = {"name": OPEN_IN_APP}+++def _rebuild() -> None:+ kinds = sorted(k for k, kind in CATALOG.kinds.items() if not kind.no_item)+ FIND_IN_APP_TOOL.update({+ "description": (+ "List things in Open Executive the person can change, with their ids: "+ + ", ".join(f"{k} ({CATALOG.kinds[k].label}s)" for k in kinds)+ + ". Call it before do_in_app to find the id of what they named. query "+ "narrows by words in the name; leave it out to list the newest."+ ),+ "input_schema": {+ "type": "object",+ "properties": {+ "kind": {"type": "string", "enum": kinds},+ "query": {"type": "string", "description": "Words from its name, as the person said them."},+ },+ "required": ["kind"],+ },+ })+ lines = []+ for name in sorted(CATALOG.actions):+ action = CATALOG.actions[name]+ extra = f" value: {action.value}." if action.value else ""+ lines.append(f"- {name} ({action.kind}): {action.does}.{extra}")+ DO_IN_APP_TOOL.update({+ "description": (+ "Do something in Open Executive that the person asked for, as its own "+ "button would: pin, rename, delete, share, turn a setting on or off. "+ f"id comes from find_in_app; for the chat you are in, use id \"{THIS}\". "+ "Some actions (deletes, shares, anything that sends as them or lets more "+ "happen on its own) leave a card for them to confirm instead: say it is "+ "waiting for their OK, never that it is done. If it is refused, say why "+ "in their words; don't retry.\n" + "\n".join(lines)+ ),+ "input_schema": {+ "type": "object",+ "properties": {+ "action": {"type": "string", "enum": sorted(CATALOG.actions)},+ "id": {"type": "string", "description": "The item's id from find_in_app, or \"this\" for this chat."},+ "value": {"type": "string", "description": "The action's value, when it takes one."},+ },+ "required": ["action", "id"],+ },+ })+ screens = sorted(CATALOG.screens)+ OPEN_IN_APP_TOOL.update({+ "description": (+ "Give the person a link to a screen in Open Executive, for something chat "+ "can't do or when they ask to go somewhere ('open my settings'). Screens: "+ + "; ".join(f"{s} ({CATALOG.screens[s][1]})" for s in screens)+ + ". The link shows under your reply."+ ),+ "input_schema": {+ "type": "object",+ "properties": {"screen": {"type": "string", "enum": screens}},+ "required": ["screen"],+ },+ })+++def register_kind(kind: Kind) -> None:+ if kind.name in CATALOG.kinds:+ raise ValueError(f"kind {kind.name!r} is already registered")+ CATALOG.kinds[kind.name] = kind+ _rebuild()+++def register_action(action: Action) -> None:+ if action.name in CATALOG.actions:+ raise ValueError(f"action {action.name!r} is already registered")+ if action.kind not in CATALOG.kinds:+ raise ValueError(f"action {action.name!r} names unknown kind {action.kind!r}")+ CATALOG.actions[action.name] = action+ _rebuild()+++def register_screen(name: str, path: str, label: str) -> None:+ if not path.startswith("/") or path.startswith("//"):+ raise ValueError(f"screen {name!r} needs an app path")+ CATALOG.screens[name] = (path, label)+ _rebuild()+++# --------------------------------------------------------------------------- #+# Who is asking, and a request that names them+# --------------------------------------------------------------------------- #+++def _session() -> Any:+ from openexecutive.orchestrator.schedule_tools import current_session++ return current_session.get()+++def _speaker() -> Any:+ from openexecutive.orchestrator.correction_tools import _speaker as speaker++ return speaker()+++def _running_app() -> Any:+ """The API's app when it is loaded (its knowledge store is on its state),+ else a stand-in whose state has nothing, so routes build their own."""+ main = sys.modules.get("openexecutive.api.main")+ app = getattr(main, "app", None)+ return app if app is not None else SimpleNamespace(state=SimpleNamespace())+++class _AsSpeaker:+ """A request naming the turn's verified speaker, for calling a route as a+ function in the turn. Only ever made from ``_speaker()``, never from+ anything the model wrote."""++ def __init__(self, person: Any, body: dict[str, Any] | None = None) -> None:+ from openexecutive.api.caller import Caller++ email = str(getattr(person, "email", "") or "").strip().lower()+ if email:+ who = Caller("user", email)+ elif getattr(person, "is_principal", False):+ # A principal with no email is who a request naming no one is.+ who = Caller("operator")+ else:+ raise Refused("I can't tell the app who you are. Do this on the screen instead.")+ self.state = SimpleNamespace(caller=who)+ self.headers: dict[str, str] = {}+ self.query_params: dict[str, str] = {}+ self.client = None+ self.app = _running_app()+ self._body = body or {}++ async def json(self) -> Any:+ return self._body+++class _WithBody:+ """A real request with the JSON body a route reads set to ``body``: for a+ route that reads its own body, run on a tap whose body is the card's."""++ def __init__(self, request: Any, body: dict[str, Any]) -> None:+ self._request = request+ self._body = body++ def __getattr__(self, name: str) -> Any:+ return getattr(self._request, name)++ async def json(self) -> Any:+ return self._body+++def with_body(request: Any, body: dict[str, Any]) -> Any:+ """``request`` reading ``body`` as its JSON (for the catalog)."""+ if isinstance(request, _AsSpeaker):+ request._body = body+ return request+ return _WithBody(request, body)+++def refusal_text(exc: BaseException) -> str:+ """What a route's refusal says, in the person's words."""+ detail = getattr(exc, "detail", None)+ if isinstance(detail, dict):+ detail = detail.get("message") or detail.get("detail")+ if isinstance(detail, list):+ detail = "; ".join(str(d.get("msg", d)) if isinstance(d, dict) else str(d) for d in detail)+ text = " ".join(str(detail or exc or "").split())+ if getattr(exc, "status_code", None) == 404 or not text:+ return text or "That isn't there, or isn't yours to change."+ return text[:300]+++def _error(text: str) -> str:+ return json.dumps({"error": text})+++def _clean_value(raw: Any) -> str:+ return " ".join(str(raw or "").split())[:_VALUE_MAX]+++def _turn_read_outside(session: Any) -> bool:+ """Whether this turn read text from outside the team or the speaker's own+ mail: from then on every action waits for a tap."""+ from openexecutive.delegation.settings import turn_delegation+ from openexecutive.orchestrator import outside_content++ try:+ if outside_content.read_outside():+ return True+ except Exception:+ return True+ pinned = turn_delegation(session)+ return bool(pinned is not None and getattr(pinned, "touched_mail", False) is True)+++# --------------------------------------------------------------------------- #+# Handlers+# --------------------------------------------------------------------------- #+++async def _items(kind: Kind, request: Any) -> list[Item]:+ from fastapi import HTTPException++ try:+ return await kind.find(request)+ except Refused as exc:+ raise exc+ except HTTPException as exc:+ raise Refused(refusal_text(exc)) from None+++def _matches(item: Item, query: str) -> bool:+ words = [w for w in query.lower().split() if w]+ text = f"{item.title} {item.detail} {item.id}".lower()+ return all(w in text for w in words)+++def _private_here() -> bool:+ """Whether only the speaker reads this conversation: their list of chats,+ settings and rules isn't for a shared chat or a channel."""+ from openexecutive.delegation.settings import private_conversation++ return private_conversation(_session())+++_NOT_PRIVATE = "Others can read this conversation, so do that in your own chat with me or on the screen."+++async def handle_find_in_app(tool_input: dict[str, Any]) -> str:+ person = _speaker()+ if person is None:+ return _error("I can only do this when I know who is asking: in the web app signed in, or your own chat app.")+ if not _private_here():+ return _error(_NOT_PRIVATE)+ kind = CATALOG.kinds.get(str(tool_input.get("kind") or ""))+ if kind is None:+ return _error(f"kind must be one of {', '.join(sorted(CATALOG.kinds))}")+ if kind.principal_only and not getattr(person, "is_principal", False):+ return _error(f"Only the account owner can change {kind.label}s.")+ try:+ items = await _items(kind, _AsSpeaker(person))+ except Refused as exc:+ return _error(str(exc))+ except Exception:+ logger.exception("find_in_app: listing %s failed", kind.name)+ return _error("Couldn't read that list just now.")+ query = _clean_value(tool_input.get("query"))+ found = [i for i in items if _matches(i, query)] if query else items+ return json.dumps({+ "kind": kind.name,+ "items": [+ {"id": i.id, "title": i.title, **({"detail": i.detail} if i.detail else {})}+ for i in found[:_FIND_MAX]+ ],+ **({"more": len(found) - _FIND_MAX} if len(found) > _FIND_MAX else {}),+ })+++def card_text(action: Action, title: str, value: str) -> str:+ """What a card says it will do, naming the item and the new value, so a+ card left after outside content was read shows exactly what a tap does."""+ named = f"“{title}”" if title else "it"+ if action.card:+ return action.card.format(title=named, value=value)+ text = action.does + (f": {named}" if title else "")+ return text + (f" → “{value}”" if value else "")+++async def _title_of(kind: Kind, request: Any, item_id: str) -> str | None:+ """The item's name when the speaker may act on it, else None."""+ if kind.no_item:+ return ""+ for item in await _items(kind, request):+ if item.id == item_id:+ return item.title+ return None+++def _audit(event: str, summary: str, details: dict[str, Any]) -> None:+ from openexecutive.audit import log_event++ session = _session()+ try:+ log_event(+ event, summary, session_id=getattr(session, "session_id", None),+ actor="executive", details=details,+ )+ except Exception:+ logger.warning("app_control: audit write failed", exc_info=True)+++async def handle_do_in_app(tool_input: dict[str, Any]) -> str:+ from fastapi import HTTPException++ session = _session()+ person = _speaker()+ if person is None or getattr(person, "id", None) is None:+ return _error("I can only do this when I know who is asking: in the web app signed in, or your own chat app.")+ if not _private_here():+ return _error(_NOT_PRIVATE)+ action = CATALOG.actions.get(str(tool_input.get("action") or ""))+ if action is None:+ return _error("Unknown action. Pick one from the list.")+ kind = CATALOG.kinds[action.kind]+ if (action.principal_only or kind.principal_only) and not getattr(person, "is_principal", False):+ return _error("Only the account owner can do that.")+ item_id = _clean_value(tool_input.get("id"))+ if item_id == THIS and action.kind == "chat":+ item_id = str(getattr(session, "session_id", "") or "")+ value = _clean_value(tool_input.get("value"))+ if action.value and not value:+ return _error(f"{action.name} needs a value: {action.value}.")+ if not item_id and not kind.no_item:+ return _error("id is required: find it with find_in_app.")+ try:+ request = _AsSpeaker(person)+ title = await _title_of(kind, request, item_id)+ if title is None:+ return _error(f"That {kind.label} isn't there, or isn't yours to change. Look it up with find_in_app.")+ if action.prepare is not None:+ with from_chat():+ value = await action.prepare(request, item_id, value)+ except Refused as exc:+ return _error(str(exc))+ except HTTPException as exc:+ return _error(refusal_text(exc))+ except Exception:+ logger.exception("do_in_app: checking %s failed", action.name)+ return _error("Couldn't check that just now. Try again in a moment.")++ details = {"action": action.name, "kind": kind.name, "id": item_id, "person_id": person.id}+ if action.needs_tap(item_id, value) or _turn_read_outside(session):+ card = card_text(action, title or "", value)+ try:+ decision_id = _leave_card(person.id, session, action, item_id, value, title or "", card)+ except Exception:+ logger.exception("do_in_app: couldn't leave the card for %s", action.name)+ return _error("Couldn't leave the card just now. Try again in a moment.")+ _audit("app_action_proposed", f"Left a card: {card[:120]}", {**details, "decision_id": decision_id})+ return json.dumps({+ "status": "waiting_for_approval",+ "decision_id": decision_id,+ "card": card,+ "note": (+ "Nothing has happened yet. A card is under this reply in the web app for "+ "them to confirm. Tell them it is waiting for their OK."+ ),+ })++ try:+ with from_chat():+ did = await action.run(request, item_id, value)+ except Refused as exc:+ return _error(str(exc))+ except HTTPException as exc:+ _audit("app_action_refused", f"{action.name} refused", {**details, "status": exc.status_code})+ return _error(refusal_text(exc))+ except Exception:+ logger.exception("do_in_app: %s failed", action.name)+ return _error("That didn't go through. Try again in a moment, or do it on the screen.")+ _audit("app_action_done", did[:200], details)+ return json.dumps({"status": "done", "did": did})+++async def handle_open_in_app(tool_input: dict[str, Any]) -> str:+ screen = CATALOG.screens.get(str(tool_input.get("screen") or ""))+ if screen is None:+ return _error(f"screen must be one of {', '.join(sorted(CATALOG.screens))}")+ path, label = screen+ return json.dumps({"status": "link", "link": path, "screen": label})+++# --------------------------------------------------------------------------- #+# The card: stored, then carried out on the speaker's tap+# --------------------------------------------------------------------------- #+++def _leave_card(+ person_id: int, session: Any, action: Action, item_id: str, value: str, title: str, card: str,+) -> int:+ from openexecutive.memory.decision_ledger import create_decision_instance++ return create_decision_instance(+ decision_class=DECISION_CLASS,+ department="",+ originating_session_id=getattr(session, "session_id", None),+ proposed_payload={+ "action": action.name, "id": item_id, "value": value, "title": title, "card": card,+ },+ idempotency_key=None,+ gate_mode="propose",+ approver_person_id=person_id,+ confidence=None,+ )+++def card_stale(created_at: str, now: datetime | None = None) -> bool:+ try:+ made = datetime.fromisoformat(created_at)+ except (TypeError, ValueError):+ return True+ if made.tzinfo is None:+ made = made.replace(tzinfo=UTC)+ return (now or datetime.now(UTC)) - made > CARD_LIFETIME+++async def carry_out(payload: dict[str, Any], request: Any) -> str:+ """Do a card's action with the tapper's own request. Raises Refused, or+ the route's HTTPException."""+ action = CATALOG.actions.get(str(payload.get("action") or ""))+ if action is None:+ raise Refused("That isn't something this app can do any more.")+ return await action.run(request, str(payload.get("id") or ""), str(payload.get("value") or ""))+++APP_TOOLS: list[dict[str, Any]] = [DO_IN_APP_TOOL, FIND_IN_APP_TOOL, OPEN_IN_APP_TOOL]+APP_TOOL_HANDLERS: dict[str, Any] = {+ FIND_IN_APP: handle_find_in_app,+ DO_IN_APP: handle_do_in_app,+ OPEN_IN_APP: handle_open_in_app,+}++_rebuild()diff --git a/packages/core/openexecutive/orchestrator/app_control_catalog.py b/packages/core/openexecutive/orchestrator/app_control_catalog.pynew file mode 100644index 00000000..dd478faa--- /dev/null+++ b/packages/core/openexecutive/orchestrator/app_control_catalog.py@@ -0,0 +1,913 @@+"""What chat can do in the app (``app_control``): chats, topics, documents,+files, alerts, watch suggestions, workflows, memory, departments, skills and+the person's own settings, plus links to screens.++Each action calls the route its button calls (see ``app_control``), so this+file is wiring: which route, what to send it, what to say after. An action+whose route checks nothing about the caller (its page is the principal's) is+``principal_only``. What waits for a tap: deletes, shares, turning on+something that sends as the person or lets more happen on its own, and+approving a workflow's waiting step.++Not here on purpose: the person's notes ("Keep track of what happens") are+private and read only through ``recall_history``, which marks the chat+private first; account, sign-in, billing and company settings stay on their+screens.+"""+from __future__ import annotations++import asyncio+import inspect+from collections.abc import Callable+from datetime import UTC, datetime+from typing import Any++from openexecutive.orchestrator.app_control import (+ Action,+ Item,+ Kind,+ Refused,+ register_action,+ register_kind,+ register_screen,+ with_body,+)+++async def _call(fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:+ """Call a route function: await an async one, run a plain one off the+ event loop (FastAPI runs those in its threadpool too)."""+ if inspect.iscoroutinefunction(fn):+ return await fn(*args, **kwargs)+ return await asyncio.to_thread(fn, *args, **kwargs)+++def _q(text: str) -> str:+ return f"“{text}”" if text else "it"+++def _on(value: str) -> bool:+ v = value.strip().lower()+ if v in ("on", "true", "yes", "enable", "enabled", "1"):+ return True+ if v in ("off", "false", "no", "disable", "disabled", "0"):+ return False+ raise Refused("Say on or off.")+++# --------------------------------------------------------------------------- #+# Chats+# --------------------------------------------------------------------------- #+++async def _find_chats(request: Any) -> list[Item]:+ from openexecutive.api.routes import sessions++ rows = await _call(sessions.get_sessions, request)+ return [+ Item(id=s.session_id, title=s.title or "Untitled chat", detail="pinned" if s.pinned_at else "")+ for s in rows+ ]+++async def _chat_title(request: Any, session_id: str) -> str:+ from openexecutive.api.routes import sessions++ summary = await _call(sessions.get_session, session_id, request)+ return str(summary.title or "")+++async def _pin_chat(request: Any, session_id: str, pinned: bool) -> str:+ from openexecutive.api.routes import sessions++ summary = await _call(sessions.update_session, session_id, sessions.SessionUpdate(pinned=pinned), request)+ return f"{'Pinned' if pinned else 'Unpinned'} {_q(summary.title)}"+++async def _rename_chat(request: Any, session_id: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ summary = await _call(sessions.update_session, session_id, sessions.SessionUpdate(title=value), request)+ return f"Renamed the chat {_q(summary.title)}"+++async def _file_chat(request: Any, session_id: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ summary = await _call(+ sessions.update_session, session_id, sessions.SessionUpdate(topic_name=value), request,+ )+ return f"Moved {_q(summary.title)} to the topic {_q(value)}"+++async def _delete_chat(request: Any, session_id: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ title = await _chat_title(request, session_id)+ await _call(sessions.delete_session_route, session_id, request)+ return f"Deleted the chat {_q(title)}"+++def _teammate(name: str) -> Any:+ """The one active team member ``name`` names (full name, first name or+ email), or Refused."""+ from openexecutive.people.store import list_people++ wanted = " ".join(name.lower().split())+ team = [p for p in list_people() if p.kind == "team" and not p.archived and p.id is not None]+ exact = [p for p in team if p.full_name.lower() == wanted or (p.email or "").lower() == wanted]+ found = exact or [p for p in team if wanted and wanted in p.full_name.lower()]+ if not found:+ raise Refused(f"There's nobody on the team called {_q(name)}.")+ if len(found) > 1:+ raise Refused(f"More than one person matches {_q(name)}: {', '.join(p.full_name for p in found[:5])}. Say which.")+ return found[0]+++async def _shared_ids(request: Any, session_id: str) -> list[int]:+ from openexecutive.api.routes import sessions++ return [s.person_id for s in await _call(sessions.get_session_shares, session_id, request)]+++async def _share_chat(request: Any, session_id: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ person = _teammate(value)+ ids = sorted({*await _shared_ids(request, session_id), person.id})+ await _call(sessions.put_session_shares, session_id, sessions.SharesUpdate(person_ids=ids), request)+ return f"Shared {_q(await _chat_title(request, session_id))} with {person.full_name}"+++async def _unshare_chat(request: Any, session_id: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ person = _teammate(value)+ current = await _shared_ids(request, session_id)+ if person.id not in current:+ raise Refused(f"This chat isn't shared with {person.full_name}.")+ ids = [i for i in current if i != person.id]+ await _call(sessions.put_session_shares, session_id, sessions.SharesUpdate(person_ids=ids), request)+ return f"Stopped sharing {_q(await _chat_title(request, session_id))} with {person.full_name}"+++# --------------------------------------------------------------------------- #+# Topics and areas+# --------------------------------------------------------------------------- #+++async def _topics(request: Any) -> list[Any]:+ from openexecutive.api.routes import sessions++ return list((await sessions.get_topics(request)).topics)+++async def _find_topics(request: Any) -> list[Item]:+ return [+ Item(id=str(t.id), title=t.name, detail=", ".join(+ x for x in ((f"in {t.area}" if t.area else ""), ("pinned" if t.pinned_at else "")) if x+ ))+ for t in await _topics(request)+ ]+++async def _topic_id(request: Any, topic_id: str) -> int:+ try:+ return int(topic_id)+ except ValueError:+ raise Refused("That isn't a topic id. Look it up with find_in_app.") from None+++async def _topic_name(request: Any, topic_id: int) -> str:+ return next((t.name for t in await _topics(request) if t.id == topic_id), "")+++async def _rename_topic(request: Any, topic_id: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ tid = await _topic_id(request, topic_id)+ topic = await _call(sessions.update_topic, tid, sessions.TopicUpdate(name=value), request)+ return f"Renamed the topic {_q(topic.name)}"+++async def _pin_topic(request: Any, topic_id: str, pinned: bool) -> str:+ from openexecutive.api.routes import sessions++ tid = await _topic_id(request, topic_id)+ topic = await _call(sessions.update_topic, tid, sessions.TopicUpdate(pinned=pinned), request)+ return f"{'Pinned' if pinned else 'Unpinned'} the topic {_q(topic.name)}"+++async def _merge_topic(request: Any, topic_id: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ tid = await _topic_id(request, topic_id)+ wanted = value.strip().lower()+ topics = await _topics(request)+ into = [t for t in topics if t.id != tid and (str(t.id) == wanted or t.name.lower() == wanted)]+ if len(into) != 1:+ raise Refused(f"There's no other topic called {_q(value)}.")+ name = await _topic_name(request, tid)+ await _call(sessions.merge_topic, tid, sessions.TopicMerge(into_id=into[0].id), request)+ return f"Moved the chats in {_q(name)} into {_q(into[0].name)}"+++async def _remove_topic(request: Any, topic_id: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ tid = await _topic_id(request, topic_id)+ name = await _topic_name(request, tid)+ await _call(sessions.ungroup_topic, tid, request)+ return f"Removed the topic {_q(name)}. Its chats are still there"+++async def _find_areas(request: Any) -> list[Item]:+ areas = sorted({t.area for t in await _topics(request) if t.area})+ return [Item(id=a, title=a) for a in areas]+++async def _rename_area(request: Any, area: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ await _call(sessions.rename_area, sessions.AreaRename(area=area, name=value), request)+ return f"Renamed the area {_q(area)} to {_q(value)}"+++async def _ungroup_area(request: Any, area: str, value: str) -> str:+ from openexecutive.api.routes import sessions++ await _call(sessions.ungroup_area, sessions.AreaUngroup(area=area), request)+ return f"Took the topics out of {_q(area)}"+++# --------------------------------------------------------------------------- #+# Documents (the Documents page) and uploaded files+# --------------------------------------------------------------------------- #+++async def _find_documents(request: Any) -> list[Item]:+ from openexecutive.api.routes import artifacts++ active = (await artifacts.list_artifacts(request, limit=200, archived=False))["artifacts"]+ archived = (await artifacts.list_artifacts(request, limit=100, archived=True))["artifacts"]+ return [Item(id=a.id, title=a.title, detail=a.format_label) for a in active] + [+ Item(id=a.id, title=a.title, detail="archived") for a in archived+ ]+++async def _document_title(request: Any, composite_id: str) -> str:+ from openexecutive.api.routes import artifacts++ return str((await artifacts.get_artifact(composite_id, request)).title)+++async def _archive_document(request: Any, composite_id: str, value: str) -> str:+ from openexecutive.api.routes import artifacts++ title = await _document_title(request, composite_id)+ await artifacts.archive_artifact(composite_id, request)+ return f"Archived {_q(title)}"+++async def _restore_document(request: Any, composite_id: str, value: str) -> str:+ from openexecutive.api.routes import artifacts++ title = await _document_title(request, composite_id)+ await artifacts.restore_artifact(composite_id, request)+ return f"Restored {_q(title)}"+++async def _delete_document(request: Any, composite_id: str, value: str) -> str:+ from openexecutive.api.routes import artifacts++ title = await _document_title(request, composite_id)+ await artifacts.delete_artifact(composite_id, request)+ return f"Deleted {_q(title)}"+++async def _find_files(request: Any) -> list[Item]:+ from openexecutive.api.routes import documents++ docs = (await documents.list_documents(request))["documents"]+ return [Item(id=d["filename"], title=d["filename"]) for d in docs]+++async def _delete_file(request: Any, filename: str, value: str) -> str:+ from openexecutive.api.routes import documents++ await documents.delete_document(filename, request)+ return f"Deleted the file {_q(filename)}"+++_SOURCES = {"drive": "Google Drive", "onedrive": "OneDrive", "notion": "Notion"}+++async def _find_sources(request: Any) -> list[Item]:+ from openexecutive.api.routes import documents++ return [Item(id=s, title=label) for s, label in _SOURCES.items() if documents._source_enabled(s)]+++async def _sync_source(request: Any, source: str, value: str) -> str:+ from openexecutive.api.routes import documents++ if source not in _SOURCES:+ raise Refused("That isn't a connected source.")+ await documents.sync_source(source) # type: ignore[arg-type]+ return f"Started syncing {_SOURCES[source]}"+++# --------------------------------------------------------------------------- #+# Alerts: only the cards the server showed or found this turn (ack_alert's rule)+# --------------------------------------------------------------------------- #+++def _trusted_alert_ids() -> set[int]:+ from openexecutive.orchestrator.schedule_tools import current_session++ session = current_session.get()+ return {int(i) for i in (getattr(session, "trusted_alert_ids", None) or set())}+++async def _find_alerts(request: Any) -> list[Item]:+ from openexecutive.alerts import store++ items = []+ for alert_id in sorted(_trusted_alert_ids()):+ alert = store.get_alert(alert_id)+ if alert is not None and alert.status in ("unread", "read"):+ items.append(Item(id=str(alert_id), title=alert.headline))+ return items+++async def _snooze_alert(request: Any, alert_id: str, value: str) -> str:+ from openexecutive.api.routes import alerts++ try:+ aid = int(alert_id)+ except ValueError:+ raise Refused("That isn't an alert id.") from None+ if aid not in _trusted_alert_ids():+ raise Refused("I can only snooze a card you were shown here. Look it up with find_alerts first.")+ try:+ until = datetime.fromisoformat(value.replace("Z", "+00:00"))+ except ValueError:+ raise Refused("Give the time as an ISO date and time, e.g. 2026-10-20T09:00:00-04:00.") from None+ alert = await _call(alerts.snooze_alert, aid, alerts.SnoozeBody(until=until), request)+ when = until.astimezone(UTC).strftime("%b %-d, %H:%M UTC")+ return f"Snoozed {_q(alert.headline)} until {when}"+++async def _prepare_clear_all(request: Any, item_id: str, value: str) -> str:+ ids = sorted(_trusted_alert_ids())+ if not ids:+ raise Refused("There are no cards in front of us to clear. Open Today first.")+ return ",".join(str(i) for i in ids[:500])+++async def _clear_alerts(request: Any, item_id: str, value: str) -> str:+ from openexecutive.api.routes import alerts++ ids = [int(i) for i in value.split(",") if i.strip().isdigit()]+ if not ids:+ raise Refused("There are no cards to clear.")+ done = await _call(alerts.bulk_ack_alerts, alerts.BulkAckBody(status="ack", alert_ids=ids), request)+ return f"Cleared {done.count} card{'' if done.count == 1 else 's'}"+++# --------------------------------------------------------------------------- #+# Watch suggestions (the principal's watch list)+# --------------------------------------------------------------------------- #+++async def _find_watch_suggestions(request: Any) -> list[Item]:+ from openexecutive.api.routes import watchlist++ out = []+ for w in await _call(watchlist.list_watchlist):+ try:+ watchlist._pending_suggestion_or_409(w.slug)+ except Exception:+ continue+ out.append(Item(id=w.slug, title=w.target, detail=(w.notes or "")[:120]))+ return out+++async def _approve_watch(request: Any, slug: str, value: str) -> str:+ from openexecutive.api.routes import watchlist++ item = await _call(watchlist.approve_watchlist_suggestion, slug)+ return f"Now watching {_q(item.target)}"+++async def _decline_watch(request: Any, slug: str, value: str) -> str:+ from openexecutive.api.routes import watchlist++ await _call(watchlist.decline_watchlist_suggestion, slug, None)+ return f"Declined watching {_q(slug)}"+++# --------------------------------------------------------------------------- #+# Workflows and their runs+# --------------------------------------------------------------------------- #+++async def _find_workflows(request: Any) -> list[Item]:+ from openexecutive.api.routes import workflows++ defs = (await workflows.list_custom_workflows())["definitions"]+ return [+ Item(id=d["name"], title=d.get("title") or d["name"], detail="on" if d.get("is_active") else "off")+ for d in defs+ ]+++async def _workflow_title(name: str) -> str:+ from openexecutive.api.routes import workflows++ found = await workflows.get_custom_workflow(name)+ return str(found.get("title") or name)+++async def _turn_workflow(request: Any, name: str, on: bool) -> str:+ from openexecutive.api.routes import workflows++ defn = await workflows.activate_custom_workflow(name, with_body(request, {"is_active": on}))+ title = defn.get("title") or name+ return f"Turned {_q(title)} {'on' if on else 'off'}"+++async def _delete_workflow(request: Any, name: str, value: str) -> str:+ from openexecutive.api.routes import workflows++ title = await _workflow_title(name)+ await workflows.delete_custom_workflow(name)+ return f"Deleted the workflow {_q(title)}"+++async def _find_runs(request: Any) -> list[Item]:+ from openexecutive.api.routes import workflows++ runs = (await workflows.list_workflow_runs(request, limit=50))["runs"]+ return [+ Item(id=r["run_id"], title=r.get("title") or r.get("workflow_name") or r["run_id"], detail=str(r.get("status") or ""))+ for r in runs+ ]+++async def _run_title(request: Any, run_id: str) -> str:+ from openexecutive.api.routes import workflows++ run = await workflows.get_workflow_run(run_id, request)+ return str(run.get("title") or run.get("workflow_name") or run_id)+++async def _rerun(request: Any, run_id: str, value: str) -> str:+ from openexecutive.api.routes import workflows++ title = await _run_title(request, run_id)+ await _call(workflows.rerun_workflow_run, run_id, request)+ return f"Started {_q(title)} again"+++async def _decide_run(request: Any, run_id: str, decision: str) -> str:+ from openexecutive.api.routes import workflows++ title = await _run_title(request, run_id)+ await workflows.decide_workflow_run(run_id, with_body(request, {"decision": decision}))+ return f"{'Approved' if decision == 'approve' else 'Turned down'} the waiting step in {_q(title)}"+++async def _delete_run(request: Any, run_id: str, value: str) -> str:+ from openexecutive.api.routes import workflows++ title = await _run_title(request, run_id)+ await workflows.delete_workflow_run(run_id, request)+ return f"Deleted the run {_q(title)}"+++# --------------------------------------------------------------------------- #+# Memory: past decisions, initiatives and advice; suggested facts+# --------------------------------------------------------------------------- #+++async def _find_memories(request: Any) -> list[Item]:+ from openexecutive.api.routes import episodic++ items = [+ Item(id=f"decision:{d.id}", title=d.summary[:120], detail="decision")+ for d in await _call(episodic.get_decisions)+ ]+ items += [+ Item(id=f"initiative:{i.id}", title=i.title[:120], detail=f"initiative, {i.status}")+ for i in await _call(episodic.get_initiatives)+ ]+ items += [+ Item(id=f"advice:{a.id}", title=(a.query_summary or a.advice_summary)[:120], detail="advice")+ for a in await _call(episodic.get_advice_list)+ ]+ return items+++def _memory_ref(ref: str) -> tuple[str, int]:+ kind, _, raw = ref.partition(":")+ if kind not in ("decision", "initiative", "advice") or not raw.isdigit():+ raise Refused("That isn't a memory id. Look it up with find_in_app.")+ return kind, int(raw)+++async def _edit_memory(request: Any, ref: str, value: str) -> str:+ from openexecutive.api.routes import episodic++ kind, mid = _memory_ref(ref)+ if kind == "decision":+ await _call(episodic.patch_decision, mid, episodic.DecisionUpdate(summary=value))+ elif kind == "initiative":+ await _call(episodic.patch_initiative, mid, episodic.InitiativeUpdate(summary=value))+ else:+ await _call(episodic.patch_advice, mid, episodic.AdviceUpdate(advice_summary=value))+ return f"Updated the {kind}"+++async def _delete_memory(request: Any, ref: str, value: str) -> str:+ from openexecutive.api.routes import episodic++ kind, mid = _memory_ref(ref)+ remove = {+ "decision": episodic.remove_decision,+ "initiative": episodic.remove_initiative,+ "advice": episodic.remove_advice,+ }[kind]+ await _call(remove, mid)+ return f"Deleted the {kind} from memory"+++async def _find_suggested_facts(request: Any) -> list[Item]:+ from openexecutive.api.routes import episodic++ page = await _call(episodic.get_facts, request, include_inactive=True, limit=200)+ return [+ Item(id=str(f.id), title=f"{f.subject}: {f.statement}"[:160], detail="waiting for your OK")+ for f in page.facts if f.status == "proposed"+ ]+++async def _review_fact(request: Any, fact_id: str, approve: bool) -> str:+ from openexecutive.api.routes import episodic++ if not fact_id.isdigit():+ raise Refused("That isn't a fact id.")+ if approve:+ fact = await _call(episodic.approve_standing_fact, int(fact_id), request)+ return f"Approved the fact {_q(fact.subject)}"+ fact = await _call(episodic.decline_standing_fact, int(fact_id), request, None)+ return f"Declined the fact {_q(fact.subject)}"+++# --------------------------------------------------------------------------- #+# Departments and skills+# --------------------------------------------------------------------------- #+++async def _find_departments(request: Any) -> list[Item]:+ from openexecutive.api.routes import departments++ return [Item(id=d.config.slug, title=d.config.title) for d in await _call(departments.list_departments)]+++async def _add_department(request: Any, item_id: str, value: str) -> str:+ from openexecutive.api.routes import departments++ made = await _call(departments.create_department, departments.DepartmentCreate(title=value))+ return f"Added the department {_q(made.config.title)}"+++async def _rename_department(request: Any, slug: str, value: str) -> str:+ from openexecutive.api.routes import departments++ await _call(departments.patch_department, slug, departments.DepartmentPatch(title=value))+ return f"Renamed the department {_q(value)}"+++async def _delete_department(request: Any, slug: str, value: str) -> str:+ from openexecutive.api.routes import departments++ title = (await _call(departments.get_department, slug)).config.title+ await _call(departments.delete_department, slug)+ return f"Deleted the department {_q(title)}"+++async def _find_skills(request: Any) -> list[Item]:+ from openexecutive.api.routes import skills++ listed = await skills.list_all_skills(include_hidden=True)+ return [Item(id=s.name, title=s.name, detail="hidden" if s.hidden else s.source) for s in listed.skills]+++async def _delete_skill(request: Any, name: str, value: str) -> str:+ from openexecutive.api.routes import skills++ await skills.delete_skill_endpoint(name, request)+ return f"Removed the skill {_q(name)}"+++async def _restore_skill(request: Any, name: str, value: str) -> str:+ from openexecutive.api.routes import skills++ await skills.restore_skill_endpoint(name, request)+ return f"Restored the skill {_q(name)}"+++# --------------------------------------------------------------------------- #+# The person's own settings+# --------------------------------------------------------------------------- #++# id → what the person calls it+_SETTINGS: dict[str, str] = {+ "quiet_hours": "Quiet hours",+ "delivery": "How messages arrive (instant or digest)",+ "urgent_through": "Let urgent things through quiet hours",+ "act_as_me": "Act as me",+ "inbox_drafts": "Draft replies to my inbox",+ "handle_it": "Handle it for me",+ "take_the_lead": "Take the lead as me",+}+# Turning these on lets the Executive send as the person or act on its own.+_WIDENING = frozenset({"act_as_me", "handle_it", "take_the_lead"})+++async def _find_settings(request: Any) -> list[Item]:+ from openexecutive.api.routes import delegation, notifications++ items = []+ try:+ n = await _call(notifications.get_notifications, request)+ q = n.quiet_hours+ items += [+ Item(id="quiet_hours", title=_SETTINGS["quiet_hours"], detail=f"{q.start}-{q.end}" if q.enabled else "off"),+ Item(id="delivery", title=_SETTINGS["delivery"], detail=n.delivery),+ Item(id="urgent_through", title=_SETTINGS["urgent_through"], detail="on" if n.urgent_through else "off"),+ ]+ except Exception:+ pass+ try:+ d = await delegation.get_delegation(request)+ state = d.model_dump()+ items.append(Item(id="act_as_me", title=_SETTINGS["act_as_me"], detail="on" if state.get("enabled") else "off"))+ items += [Item(id=k, title=_SETTINGS[k]) for k in ("inbox_drafts", "handle_it", "take_the_lead")]+ except Exception:+ pass+ return items+++def _quiet_hours(value: str, current: Any) -> Any:+ from openexecutive.people.notifications import QuietHours++ v = value.strip().lower()+ if v in ("off", "none", "no"):+ return current.model_copy(update={"enabled": False})+ start, sep, end = v.replace(" to ", "-").replace("–", "-").partition("-")+ if not sep:+ raise Refused("Give quiet hours as start-end in 24-hour time, e.g. 22:00-07:00, or off.")+ try:+ return QuietHours(enabled=True, start=start.strip(), end=end.strip(), days=current.days)+ except ValueError:+ raise Refused("Give quiet hours as start-end in 24-hour time, e.g. 22:00-07:00, or off.") from None+++async def _change_setting(request: Any, setting: str, value: str) -> str:+ from openexecutive.api.routes import delegation, notifications++ label = _SETTINGS.get(setting)+ if label is None:+ raise Refused("That isn't a setting I can change.")+ if setting in ("quiet_hours", "delivery", "urgent_through"):+ n = await _call(notifications.get_notifications, request)+ quiet, delivery, urgent = n.quiet_hours, n.delivery, n.urgent_through+ if setting == "quiet_hours":+ quiet = _quiet_hours(value, quiet)+ said = f"{quiet.start}-{quiet.end}" if quiet.enabled else "off"+ elif setting == "delivery":+ if value.strip().lower() not in ("instant", "digest"):+ raise Refused("Say instant or digest.")+ delivery = value.strip().lower()+ said = delivery+ else:+ urgent = _on(value)+ said = "on" if urgent else "off"+ await _call(notifications.update_notifications, request, notifications.NotificationsUpdate(+ quiet_hours=quiet, delivery=delivery, urgent_through=urgent, timezone=n.timezone,+ ))+ return f"Set {label} to {said}"+ on = _on(value)+ if setting == "act_as_me":+ await delegation.update_delegation(request, delegation.DelegationUpdate(enabled=on))+ elif setting == "inbox_drafts":+ await delegation.update_delegation_inbox(request, delegation.InboxUpdate(enabled=on))+ elif setting == "handle_it":+ await delegation.update_delegation_handle_it(request, delegation.HandleItUpdate(enabled=on))+ else:+ await delegation.update_take_the_lead_as_you(request, delegation.LeadUpdate(enabled=on))+ return f"Turned {label} {'on' if on else 'off'}"+++def _setting_needs_tap(setting: str, value: str) -> bool:+ if setting not in _WIDENING:+ return False+ try:+ return _on(value)+ except Refused:+ return True+++async def _check_inbox(request: Any, item_id: str, value: str) -> str:+ from openexecutive.api.routes import delegation++ await delegation.check_delegation_inbox(request)+ return "Started checking your inbox"+++async def _find_lead_rules(request: Any) -> list[Item]:+ from openexecutive.api.routes import delegation++ rules = (await _call(delegation.get_my_lead_rules, request)).rules+ return [Item(id=str(r.id), title=f"{r.kind}: {r.value}") for r in rules]+++async def _add_lead_rule(request: Any, item_id: str, value: str) -> str:+ from openexecutive.api.routes import delegation++ kind, sep, text = value.partition(":")+ if not sep:+ raise Refused("Give the rule as kind: value, e.g. domain: acme.com. Kinds: person, domain, words, amount.")+ await _call(+ delegation.add_my_lead_rule, request, delegation.LeadRuleIn(kind=kind.strip().lower(), value=text.strip()),+ )+ return f"Added the rule: always ask first about {kind.strip().lower()} {_q(text.strip())}"+++async def _remove_lead_rule(request: Any, rule_id: str, value: str) -> str:+ from openexecutive.api.routes import delegation++ if not rule_id.isdigit():+ raise Refused("That isn't a rule id.")+ await _call(delegation.delete_my_lead_rule, request, int(rule_id))+ return "Removed the rule"+++# --------------------------------------------------------------------------- #+# Registration+# --------------------------------------------------------------------------- #+++def _fixed(fn: Callable[..., Any], *extra: Any) -> Any:+ async def run(request: Any, item_id: str, value: str) -> str:+ return await fn(request, item_id, *extra) # type: ignore[no-any-return]++ return run+++async def _nothing(request: Any) -> list[Item]:+ return []+++_KINDS = (+ Kind("chat", "chat", _find_chats),+ Kind("topic", "chat topic", _find_topics),+ Kind("topic_area", "topic area", _find_areas),+ Kind("document", "document", _find_documents),+ Kind("file", "uploaded file", _find_files, principal_only=True),+ Kind("source", "synced source", _find_sources, principal_only=True),+ Kind("alert", "card on Today", _find_alerts),+ Kind("alert_board", "the cards on Today", _nothing, principal_only=True, no_item=True),+ Kind("watch_suggestion", "suggested watch", _find_watch_suggestions, principal_only=True),+ Kind("workflow", "workflow", _find_workflows, principal_only=True),+ Kind("workflow_run", "workflow run", _find_runs),+ Kind("memory", "memory (decision, initiative or advice)", _find_memories, principal_only=True),+ Kind("suggested_fact", "suggested fact", _find_suggested_facts, principal_only=True),+ Kind("department", "department", _find_departments, principal_only=True),+ Kind("new_department", "new department", _nothing, principal_only=True, no_item=True),+ Kind("skill", "skill", _find_skills, principal_only=True),+ Kind("setting", "setting", _find_settings),+ Kind("inbox", "inbox", _nothing, no_item=True),+ Kind("lead_rule", "Take the lead rule", _find_lead_rules),+ Kind("new_lead_rule", "new Take the lead rule", _nothing, no_item=True),+)++_ACTIONS = (+ # Chats+ Action("pin_chat", "chat", "Pin a chat to the top of the chat list", _fixed(_pin_chat, True)),+ Action("unpin_chat", "chat", "Unpin a chat", _fixed(_pin_chat, False)),+ Action("rename_chat", "chat", "Rename a chat", _rename_chat, value="the new name"),+ Action("move_chat_to_topic", "chat", "File a chat under a topic (made if new)", _file_chat, value="the topic's name"),+ Action("delete_chat", "chat", "Delete a chat for good", _delete_chat, confirm=True,+ card="Delete the chat {title}"),+ Action("share_chat", "chat", "Share a chat with a team member, who can then read and write in it",+ _share_chat, confirm=True, value="the person's name", card="Share the chat {title} with {value}"),+ Action("unshare_chat", "chat", "Stop sharing a chat with someone", _unshare_chat, value="the person's name"),+ # Topics+ Action("rename_topic", "topic", "Rename a chat topic", _rename_topic, value="the new name"),+ Action("pin_topic", "topic", "Pin a chat topic", _fixed(_pin_topic, True)),+ Action("unpin_topic", "topic", "Unpin a chat topic", _fixed(_pin_topic, False)),+ Action("merge_topic", "topic", "Move every chat in a topic into another topic", _merge_topic,+ value="the other topic's name"),+ Action("remove_topic", "topic", "Remove a topic; its chats stay, under no topic", _remove_topic),+ Action("rename_topic_area", "topic_area", "Rename an area that groups topics", _rename_area,+ value="the new name"),+ Action("ungroup_topic_area", "topic_area", "Take the topics out of an area", _ungroup_area),+ # Documents and files+ Action("archive_document", "document", "Archive a document (it can be restored)", _archive_document),+ Action("restore_document", "document", "Restore an archived document", _restore_document),+ Action("delete_document", "document", "Delete a document for good", _delete_document, confirm=True,+ card="Delete the document {title}"),+ Action("delete_file", "file", "Delete an uploaded file and what was learned from it", _delete_file,+ confirm=True, card="Delete the uploaded file {title}"),+ Action("sync_source", "source", "Sync a connected source now", _sync_source),+ # Alerts+ Action("snooze_alert", "alert", "Hide a card on Today until a time, when it comes back", _snooze_alert,+ value="when it comes back, ISO 8601 with a zone, at most 30 days out"),+ Action("clear_all_alerts", "alert_board", "Clear every card shown on Today", _clear_alerts, confirm=True,+ card="Clear every card on Today", prepare=_prepare_clear_all),+ # Watch suggestions+ Action("approve_watch", "watch_suggestion", "Start a suggested watch", _approve_watch),+ Action("decline_watch", "watch_suggestion", "Decline a suggested watch", _decline_watch),+ # Workflows+ Action("turn_on_workflow", "workflow", "Turn a workflow on so it runs on its schedule",+ _fixed(_turn_workflow, True), confirm=True, card="Turn on the workflow {title}"),+ Action("turn_off_workflow", "workflow", "Turn a workflow off", _fixed(_turn_workflow, False)),+ Action("delete_workflow", "workflow", "Delete a workflow for good", _delete_workflow, confirm=True,+ card="Delete the workflow {title}"),+ Action("rerun_workflow_run", "workflow_run", "Run a failed scheduled run again", _rerun),+ Action("approve_workflow_step", "workflow_run", "Approve a run's step that is waiting for a yes",+ _fixed(_decide_run, "approve"), confirm=True, card="Approve the waiting step in {title}"),+ Action("reject_workflow_step", "workflow_run", "Turn down a run's step that is waiting for a yes",+ _fixed(_decide_run, "reject")),+ Action("delete_workflow_run", "workflow_run", "Delete a run and what it made", _delete_run, confirm=True,+ card="Delete the run {title}"),+ # Memory+ Action("edit_memory", "memory", "Change what a past decision, initiative or advice says", _edit_memory,+ value="what it should say now"),+ Action("delete_memory", "memory", "Delete a past decision, initiative or advice from memory", _delete_memory,+ confirm=True, card="Delete from memory: {title}"),+ Action("approve_fact", "suggested_fact", "Approve a fact a teammate suggested", _fixed(_review_fact, True)),+ Action("decline_fact", "suggested_fact", "Decline a fact a teammate suggested", _fixed(_review_fact, False)),+ # Departments+ Action("add_department", "new_department", "Add a department (use id \"new\")", _add_department,+ value="its name"),+ Action("rename_department", "department", "Rename a department", _rename_department, value="the new name"),+ Action("delete_department", "department", "Delete a department", _delete_department, confirm=True,+ card="Delete the department {title}"),+ # Skills+ Action("delete_skill", "skill", "Delete a company skill, undo a change to one, or hide a built-in one",+ _delete_skill, confirm=True, card="Remove the skill {title}"),+ Action("restore_skill", "skill", "Bring back a hidden built-in skill", _restore_skill),+ # Settings+ Action("change_setting", "setting",+ "Change one of the person's own settings: quiet_hours (start-end or off), delivery "+ "(instant or digest), urgent_through, act_as_me, inbox_drafts, handle_it, take_the_lead (on or off)",+ _change_setting, confirm=_setting_needs_tap, value="the new value", card="Set {title} to {value}"),+ Action("check_inbox_now", "inbox", "Check the person's inbox for emails to draft replies to now (use id \"inbox\")",+ _check_inbox),+ Action("add_lead_rule", "new_lead_rule",+ "Add a rule that makes Take the lead ask first (use id \"new\")", _add_lead_rule,+ value="kind: value, kinds person, domain, words, amount"),+ Action("remove_lead_rule", "lead_rule", "Remove a Take the lead rule, so more goes ahead on its own",+ _remove_lead_rule, confirm=True, card="Remove the Take the lead rule {title}"),+)++# Where a link from chat can go (the web app's own paths).+_SCREENS = (+ ("today", "/today", "Today"),+ ("chats", "/chats", "all chats"),+ ("settings", "/settings", "Settings"),+ ("notifications", "/settings/notifications", "Settings, Notifications"),+ ("act_as_me", "/settings/act-as-me", "Settings, Act as me"),+ ("memory_settings", "/settings/memory", "Settings, Memory"),+ ("people", "/people", "People"),+ ("departments", "/departments", "Departments"),+ ("goals", "/goals", "Goals"),+ ("watchlist", "/watchlist", "Watch list"),+ ("documents", "/artifacts", "Documents"),+ ("knowledge", "/knowledge", "Knowledge (uploaded files)"),+ ("memories", "/memories", "Memory"),+ ("skills", "/skills", "Skills"),+ ("workflows", "/jobs", "Workflows"),+ ("guide", "/guide", "User guide"),+)+++def install() -> None:+ """Add this repo's kinds, actions and screens (once)."""+ from openexecutive.orchestrator.app_control import CATALOG++ if "chat" in CATALOG.kinds:+ return+ for kind in _KINDS:+ register_kind(kind)+ for action in _ACTIONS:+ register_action(action)+ for name, path, label in _SCREENS:+ register_screen(name, path, label)+++install()diff --git a/packages/core/openexecutive/orchestrator/executive.py b/packages/core/openexecutive/orchestrator/executive.pyindex 66479609..7a20c264 100644--- a/packages/core/openexecutive/orchestrator/executive.py+++ b/packages/core/openexecutive/orchestrator/executive.py@@ -41,6 +41,7 @@ from openexecutive.memory.workspace_settings import (pin_turn_workspace_mode,)from openexecutive.orchestrator import (+ app_control_catalog, # noqa: F401 (fills the app tools' catalog)claim_check,department_gate,extensions,@@ -62,6 +63,10 @@ from openexecutive.orchestrator.alert_tools import (handle_create_alert,)from openexecutive.orchestrator.answer_sources import TurnSources, record_web_sources+from openexecutive.orchestrator.app_control import (+ APP_TOOL_HANDLERS,+ APP_TOOLS,+)from openexecutive.orchestrator.artifact_tools import (DRAFT_ARTIFACT_TOOL_HANDLERS,DRAFT_ARTIFACT_TOOLS,@@ -768,6 +773,7 @@ _ALL_SKILL_TOOLS = [*FORM_TOOLS,*GUIDE_TOOLS,*PYTHON_JOB_TOOLS,+ *APP_TOOLS,]@@ -799,6 +805,7 @@ _ALL_SKILL_HANDLERS = {**FORM_TOOL_HANDLERS,**GUIDE_TOOL_HANDLERS,**PYTHON_JOB_TOOL_HANDLERS,+ **APP_TOOL_HANDLERS,}diff --git a/packages/core/openexecutive/orchestrator/schedule_tools.py b/packages/core/openexecutive/orchestrator/schedule_tools.pyindex 8721a0ec..d46ab197 100644--- a/packages/core/openexecutive/orchestrator/schedule_tools.py+++ b/packages/core/openexecutive/orchestrator/schedule_tools.py@@ -1846,6 +1846,11 @@ UNATTENDED_WITHHELD_TOOLS: frozenset[str] = frozenset({"remember_fact","resolve_roster_request","update_company_profile",+ # App control (orchestrator/app_control.py) acts as the person asking, and+ # its cards wait for their tap: nobody is there to ask or to tap.+ "do_in_app",+ "find_in_app",+ "open_in_app",})@@ -2239,6 +2244,8 @@ def mcp_client_withheld_error(tool_name: str, *, acting: bool = False) -> str:# the variant keeps a stable tool prefix of its own.SHARED_CHAT_WITHHELD_TOOLS: frozenset[str] = frozenset({"archive_person",+ # Changes in the app as the owner: their word, not a guest's.+ "do_in_app",# Invites and cancellations mail the attendees."cancel_calendar_event","create_calendar_event",diff --git a/packages/core/openexecutive/orchestrator/tool_groups.py b/packages/core/openexecutive/orchestrator/tool_groups.pyindex c2816c7f..914a40b5 100644--- a/packages/core/openexecutive/orchestrator/tool_groups.py+++ b/packages/core/openexecutive/orchestrator/tool_groups.py@@ -74,6 +74,12 @@ GROUPS: dict[str, tuple[str, tuple[str, ...]]] = {"write, read back or list documents such as memos, reports and plans (artifacts)",("draft_artifact", "get_artifact", "list_artifacts"),),+ "app": (+ "do what the app's own buttons do: pin, rename, delete or share chats; topics, documents, "+ "files, cards on Today, workflows, memory, departments, skills, the person's own settings; "+ "links to screens",+ ("do_in_app", "find_in_app", "open_in_app"),+ ),"messaging": ("Slack, Telegram and Discord messages, department messages, company broadcasts",(diff --git a/packages/core/tests/unit/test_action_chips.py b/packages/core/tests/unit/test_action_chips.pyindex e7ece6ae..b4c073a3 100644--- a/packages/core/tests/unit/test_action_chips.py+++ b/packages/core/tests/unit/test_action_chips.py@@ -347,6 +347,8 @@ _KNOWN_READ_ONLY_TOOLS: frozenset[str] = frozenset({"read_my_email_attachment","my_email_awaiting_reply","my_email_read_before",+ # app_control — a list of what the person may change+ "find_in_app",})@@ -356,6 +358,7 @@ def _all_registered_tool_names() -> set[str]:Kept here as a helper so both drift tests use the exact same sourceof truth — drift between them would defeat the guard."""+ from openexecutive.orchestrator.app_control import APP_TOOL_HANDLERSfrom openexecutive.orchestrator.artifact_tools import DRAFT_ARTIFACT_TOOL_HANDLERSfrom openexecutive.orchestrator.broadcast_tools import BROADCAST_TOOL_HANDLERSfrom openexecutive.orchestrator.calendar_tools import CALENDAR_TOOL_HANDLERS@@ -385,6 +388,7 @@ def _all_registered_tool_names() -> set[str]:| set(DRAFT_ARTIFACT_TOOL_HANDLERS)| set(MCP_TOOL_NAMES)| set(WORKFLOW_RUN_TOOL_HANDLERS)+ | set(APP_TOOL_HANDLERS)# Act as me: its own registry, offered per turn (never _ALL_SKILL_TOOLS).| set(DELEGATION_TOOL_HANDLERS)# `create_alert` is in chat module rather than a HANDLERS dict.diff --git a/packages/core/tests/unit/test_app_control.py b/packages/core/tests/unit/test_app_control.pynew file mode 100644index 00000000..aaab7907--- /dev/null+++ b/packages/core/tests/unit/test_app_control.py@@ -0,0 +1,440 @@+"""App control from chat (orchestrator/app_control.py and its catalog): the+Executive does what the app's buttons do, through the same routes, and leaves+a card for anything that waits for a tap (api/routes/decisions.py)."""+from __future__ import annotations++import asyncio+import json+from collections.abc import Iterator+from datetime import UTC, datetime, timedelta+from pathlib import Path+from typing import Any++import pytest+from fastapi import FastAPI+from fastapi.testclient import TestClient++from openexecutive.api.routes import chat as chat_route+from openexecutive.api.routes import decisions as decisions_route+from openexecutive.api.routes import sessions as sessions_route+from openexecutive.departments import registry as dept_registry+from openexecutive.departments import store as dept_store+from openexecutive.memory import decision_ledger, episodic, session_store+from openexecutive.monitoring import store as monitoring_store+from openexecutive.orchestrator import app_control, app_control_catalog, outside_content+from openexecutive.orchestrator.action_chips import summarize_action+from openexecutive.orchestrator.schedule_tools import set_session+from openexecutive.orchestrator.session import Session+from openexecutive.people import registry as people_registry+from openexecutive.people import store as people_store++OWNER = {"x-caller-email": "[email protected]"}+BEN = {"x-caller-email": "[email protected]"}++[email protected](autouse=True)+def db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[Path]:+ # Stores that bind ./episodic_memory.db as a default argument find it here.+ monkeypatch.chdir(tmp_path)+ path = Path("./episodic_memory.db").resolve()+ monkeypatch.setattr(episodic, "DB_PATH", path)+ monkeypatch.setattr(session_store, "DB_PATH", path)+ monkeypatch.setattr(people_store, "DB_PATH", path)+ monkeypatch.setattr(decision_ledger, "_db_path", lambda: path)+ monkeypatch.setattr(dept_store, "DB_PATH", path)+ episodic.initialize_db(path)+ dept_store.initialize_db(path)+ monitoring_store.initialize_db(path)+ dept_registry.invalidate()+ people_store.initialize_db(path)+ for var in ("OE_LOCAL_LOGIN", "OE_PUBLIC_DEPLOYMENT", "BACKEND_SHARED_SECRET"):+ monkeypatch.delenv(var, raising=False)+ monkeypatch.setattr("openexecutive.audit.log_event", lambda *_a, **_k: None)+ chat_route._sessions.clear()+ chat_route._session_starters.clear()+ people_registry.invalidate()+ yield path+ people_registry.invalidate()+++def roster() -> dict[str, Any]:+ owner = people_store.upsert_person(full_name="Olivia Owner", is_principal=True, email="[email protected]")+ ben = people_store.upsert_person(full_name="Ben Teammate", email="[email protected]")+ people_registry.invalidate()+ return {"owner": people_store.get_person(owner), "ben": people_store.get_person(ben)}+++def client() -> Iterator[TestClient]:+ app = FastAPI()+ app.include_router(sessions_route.router)+ app.include_router(decisions_route.router)+ with TestClient(app) as c:+ yield c+++def _chat(owner_id: int, sid: str, title: str) -> str:+ session_store.create_session(sid, title, "2026-10-01T09:00:00+00:00", caller_person_id=owner_id)+ session_store.save_message(sid, "user", "question", sender_person_id=owner_id)+ return sid+++def _web(person: Any, session_id: str) -> Session:+ return Session(session_id=session_id, from_web_chat=True, caller_person_id=person.id,+ web_caller_signed_in=True)+++def _run(handler: Any, args: dict[str, Any], session: Session | None) -> dict[str, Any]:+ async def go() -> str:+ if session is None:+ return str(await handler(args))+ with set_session(session):+ return str(await handler(args))++ return dict(json.loads(asyncio.run(go())))+++def _meta(sid: str) -> dict[str, Any] | None:+ return session_store.get_session_metadata(sid)+++# --------------------------------------------------------------------------- #+# Doing it now+# --------------------------------------------------------------------------- #+++def test_pin_and_rename_this_chat(roster: dict[str, Any]) -> None:+ sid = _chat(roster["owner"].id, "s-1", "Old name")+ session = _web(roster["owner"], sid)+ out = _run(app_control.handle_do_in_app, {"action": "pin_chat", "id": "this"}, session)+ assert out == {"status": "done", "did": "Pinned “Old name”"}+ assert (_meta(sid) or {}).get("pinned_at")+ out = _run(app_control.handle_do_in_app, {"action": "rename_chat", "id": "this", "value": "Q3 plan"}, session)+ assert out["status"] == "done"+ assert (_meta(sid) or {})["title"] == "Q3 plan"+++def test_find_lists_only_the_speakers_chats(roster: dict[str, Any]) -> None:+ _chat(roster["owner"].id, "s-own", "Pricing review")+ _chat(roster["ben"].id, "s-ben", "Ben's pricing notes")+ out = _run(app_control.handle_find_in_app, {"kind": "chat", "query": "pricing"},+ _web(roster["owner"], "s-own"))+ assert [i["id"] for i in out["items"]] == ["s-own"]+++def test_someone_elses_chat_is_not_there(roster: dict[str, Any]) -> None:+ sid = _chat(roster["owner"].id, "s-owner", "Board prep")+ out = _run(app_control.handle_do_in_app, {"action": "rename_chat", "id": sid, "value": "mine now"},+ _web(roster["ben"], "s-x"))+ assert "error" in out+ assert (_meta(sid) or {})["title"] == "Board prep"+++def test_nobody_verified_is_refused(roster: dict[str, Any]) -> None:+ sid = _chat(roster["owner"].id, "s-1", "Board prep")+ assert "error" in _run(app_control.handle_do_in_app, {"action": "pin_chat", "id": sid}, None)+ unverified = Session(session_id="s-mail", origin_channel="email")+ assert "error" in _run(app_control.handle_do_in_app, {"action": "pin_chat", "id": sid}, unverified)+++def test_owner_only_kinds_are_refused_for_a_teammate(roster: dict[str, Any]) -> None:+ out = _run(app_control.handle_find_in_app, {"kind": "department"}, _web(roster["ben"], "s-b"))+ assert "error" in out+ out = _run(app_control.handle_do_in_app, {"action": "add_department", "id": "new", "value": "Ops"},+ _web(roster["ben"], "s-b"))+ assert "error" in out+++def test_a_value_is_required_where_the_action_takes_one(roster: dict[str, Any]) -> None:+ sid = _chat(roster["owner"].id, "s-1", "Board prep")+ out = _run(app_control.handle_do_in_app, {"action": "rename_chat", "id": sid}, _web(roster["owner"], sid))+ assert "needs a value" in out["error"]+++def test_a_route_refusal_comes_back_in_words(roster: dict[str, Any]) -> None:+ sid = _chat(roster["owner"].id, "s-1", "Board prep")+ out = _run(app_control.handle_do_in_app, {"action": "rename_chat", "id": sid, "value": " "},+ _web(roster["owner"], sid))+ assert "error" in out+++# --------------------------------------------------------------------------- #+# Waiting for a tap+# --------------------------------------------------------------------------- #+++def _card(decision_id: int) -> decision_ledger.DecisionInstance:+ found = decision_ledger.get_decision_instance(decision_id)+ assert found is not None+ return found+++def test_delete_leaves_a_card_and_the_tap_deletes(roster: dict[str, Any], client: TestClient) -> None:+ sid = _chat(roster["owner"].id, "s-del", "Old pricing")+ out = _run(app_control.handle_do_in_app, {"action": "delete_chat", "id": "this"}, _web(roster["owner"], sid))+ assert out["status"] == "waiting_for_approval"+ assert out["card"] == "Delete the chat “Old pricing”"+ assert _meta(sid) is not None # nothing happened yet+ card = _card(out["decision_id"])+ assert card.decision_class == "app_action"+ assert card.approver_person_id == roster["owner"].id++ # Nobody else sees or answers it.+ assert client.get(f"/decisions/{card.id}", headers=BEN).status_code == 404+ assert client.post(f"/decisions/{card.id}/approve", json={}, headers=BEN).status_code == 404++ res = client.post(f"/decisions/{card.id}/approve", json={}, headers=OWNER)+ assert res.status_code == 200, res.text+ assert res.json()["status"] == decision_ledger.STATUS_APPROVED_UNCHANGED+ assert _meta(sid) is None+ # Once only.+ assert client.post(f"/decisions/{card.id}/approve", json={}, headers=OWNER).status_code == 409+++def test_dismissing_the_card_does_nothing(roster: dict[str, Any], client: TestClient) -> None:+ sid = _chat(roster["owner"].id, "s-keep", "Keep me")+ out = _run(app_control.handle_do_in_app, {"action": "delete_chat", "id": sid}, _web(roster["owner"], sid))+ res = client.post(f"/decisions/{out['decision_id']}/reject", json={}, headers=OWNER)+ assert res.status_code == 200+ assert _meta(sid) is not None+++def test_a_stale_card_is_turned_down(roster: dict[str, Any], client: TestClient) -> None:+ sid = _chat(roster["owner"].id, "s-old", "Old")+ out = _run(app_control.handle_do_in_app, {"action": "delete_chat", "id": sid}, _web(roster["owner"], sid))+ old = (datetime.now(UTC) - timedelta(days=2)).isoformat()+ with episodic._get_conn() as conn:+ conn.execute("UPDATE decision_instances SET created_at = ? WHERE id = ?", (old, out["decision_id"]))+ res = client.post(f"/decisions/{out['decision_id']}/approve", json={}, headers=OWNER)+ assert res.status_code == 409+ assert _meta(sid) is not None+++def test_a_refusal_on_the_tap_is_recorded(roster: dict[str, Any], client: TestClient) -> None:+ sid = _chat(roster["owner"].id, "s-gone", "Gone")+ out = _run(app_control.handle_do_in_app, {"action": "delete_chat", "id": sid}, _web(roster["owner"], sid))+ session_store.delete_session(sid)+ res = client.post(f"/decisions/{out['decision_id']}/approve", json={}, headers=OWNER)+ assert res.status_code == 404+ assert _card(out["decision_id"]).status == decision_ledger.STATUS_FAILED+++def test_after_an_outside_read_everything_waits(roster: dict[str, Any]) -> None:+ sid = _chat(roster["owner"].id, "s-out", "Board prep")+ session = _web(roster["owner"], sid)+ state = outside_content.begin_turn(session)+ try:+ outside_content.mark("read_document")+ out = _run(app_control.handle_do_in_app, {"action": "rename_chat", "id": sid, "value": "pwned"}, session)+ finally:+ outside_content.end_turn(state)+ assert out["status"] == "waiting_for_approval"+ assert (_meta(sid) or {})["title"] == "Board prep"+++def test_turning_on_act_as_me_waits_but_off_does_not() -> None:+ action = app_control.CATALOG.actions["change_setting"]+ assert action.needs_tap("act_as_me", "on")+ assert action.needs_tap("handle_it", "on")+ assert action.needs_tap("take_the_lead", "yes")+ assert not action.needs_tap("handle_it", "off")+ assert not action.needs_tap("quiet_hours", "22:00-07:00")+++def test_sharing_waits_for_a_tap(roster: dict[str, Any], client: TestClient) -> None:+ sid = _chat(roster["owner"].id, "s-share", "Hiring plan")+ out = _run(app_control.handle_do_in_app, {"action": "share_chat", "id": sid, "value": "Ben"},+ _web(roster["owner"], sid))+ assert out["card"] == "Share the chat “Hiring plan” with Ben"+ res = client.post(f"/decisions/{out['decision_id']}/approve", json={}, headers=OWNER)+ assert res.status_code == 200, res.text+ assert [r["person_id"] for r in session_store.shared_with(sid)] == [roster["ben"].id]+++# --------------------------------------------------------------------------- #+# Topics, settings, links, chips, the catalog+# --------------------------------------------------------------------------- #+++def test_file_a_chat_under_a_topic_then_rename_the_topic(roster: dict[str, Any]) -> None:+ sid = _chat(roster["owner"].id, "s-t", "Lease terms")+ session = _web(roster["owner"], sid)+ assert _run(app_control.handle_do_in_app,+ {"action": "move_chat_to_topic", "id": "this", "value": "Main St property"}, session)["status"] == "done"+ found = _run(app_control.handle_find_in_app, {"kind": "topic"}, session)["items"]+ assert [t["title"] for t in found] == ["Main St property"]+ out = _run(app_control.handle_do_in_app,+ {"action": "rename_topic", "id": found[0]["id"], "value": "Main Street"}, session)+ assert out == {"status": "done", "did": "Renamed the topic “Main Street”"}+++def test_quiet_hours_from_chat(roster: dict[str, Any], monkeypatch: pytest.MonkeyPatch) -> None:+ from openexecutive.people import notifications++ monkeypatch.setattr(notifications, "DB_PATH", Path("./episodic_memory.db").resolve(), raising=False)+ session = _web(roster["owner"], "s-q")+ out = _run(app_control.handle_do_in_app,+ {"action": "change_setting", "id": "quiet_hours", "value": "21:30-06:45"}, session)+ assert out == {"status": "done", "did": "Set Quiet hours to 21:30-06:45"}, out+ saved = notifications.get_notification_settings(roster["owner"].id)+ assert (saved.quiet_hours.enabled, saved.quiet_hours.start, saved.quiet_hours.end) == (True, "21:30", "06:45")+++def test_open_in_app_gives_an_app_link() -> None:+ out = _run(app_control.handle_open_in_app, {"screen": "notifications"}, None)+ assert out == {"status": "link", "link": "/settings/notifications", "screen": "Settings, Notifications"}+ assert "error" in _run(app_control.handle_open_in_app, {"screen": "https://evil.example"}, None)+ with pytest.raises(ValueError):+ app_control.register_screen("evil", "https://evil.example", "x")+++def test_chips() -> None:+ done = summarize_action(tool_name="do_in_app", tool_input={},+ tool_result=json.dumps({"status": "done", "did": "Pinned “Q3”"}))+ assert done is not None and done["summary"] == "Pinned “Q3”"+ waiting = summarize_action(+ tool_name="do_in_app", tool_input={},+ tool_result=json.dumps({"status": "waiting_for_approval", "decision_id": 7, "card": "Delete the chat “Q3”"}),+ )+ assert waiting is not None+ assert waiting["summary"] == "Waiting for your OK: Delete the chat “Q3”"+ assert waiting["decision_id"] == 7+ assert summarize_action(tool_name="do_in_app", tool_input={}, tool_result=json.dumps({"error": "no"})) is None+ link = summarize_action(tool_name="open_in_app", tool_input={},+ tool_result=json.dumps({"status": "link", "link": "/today", "screen": "Today"}))+ assert link is not None and link["link"] == "/today"+ assert summarize_action(tool_name="open_in_app", tool_input={},+ tool_result=json.dumps({"status": "link", "link": "//evil.example"})) is None+++def test_the_catalog_is_whole() -> None:+ catalog = app_control.CATALOG+ assert app_control_catalog # installed on import+ for action in catalog.actions.values():+ assert action.kind in catalog.kinds+ if action.needs_tap("x", "on"):+ assert action.card, action.name+ schema = app_control.DO_IN_APP_TOOL["input_schema"]["properties"]["action"]["enum"]+ assert schema == sorted(catalog.actions)+ for name in ("pin_chat", "rename_chat", "delete_chat"):+ assert name in app_control.DO_IN_APP_TOOL["description"]+ for name, action in catalog.actions.items():+ destructive = name.startswith("delete_") or name.startswith("share_")+ if destructive:+ assert action.needs_tap("x", ""), name+++def test_registering_twice_is_refused() -> None:+ with pytest.raises(ValueError):+ app_control.register_action(app_control.CATALOG.actions["pin_chat"])+++def test_departments_add_rename_and_delete(roster: dict[str, Any], client: TestClient) -> None:+ session = _web(roster["owner"], "s-d")+ out = _run(app_control.handle_do_in_app, {"action": "add_department", "id": "new", "value": "Field Ops"}, session)+ assert out == {"status": "done", "did": "Added the department “Field Ops”"}, out+ found = _run(app_control.handle_find_in_app, {"kind": "department", "query": "field"}, session)["items"]+ assert [d["title"] for d in found] == ["Field Ops"]+ slug = found[0]["id"]+ out = _run(app_control.handle_do_in_app, {"action": "rename_department", "id": slug, "value": "Field"}, session)+ assert out["status"] == "done", out+ out = _run(app_control.handle_do_in_app, {"action": "delete_department", "id": slug}, session)+ assert out["card"] == "Delete the department “Field”"+ res = client.post(f"/decisions/{out['decision_id']}/approve", json={}, headers=OWNER)+ assert res.status_code == 200, res.text+ assert _run(app_control.handle_find_in_app, {"kind": "department", "query": "field"}, session)["items"] == []+++def test_memory_edit_and_delete(roster: dict[str, Any], client: TestClient) -> None:+ episodic.store_decision("sales", "Raise prices 5%")+ decision_id = episodic.list_decisions()[0].id+ session = _web(roster["owner"], "s-m")+ found = _run(app_control.handle_find_in_app, {"kind": "memory", "query": "prices"}, session)["items"]+ assert found == [{"id": f"decision:{decision_id}", "title": "Raise prices 5%", "detail": "decision"}]+ out = _run(app_control.handle_do_in_app,+ {"action": "edit_memory", "id": f"decision:{decision_id}", "value": "Raise prices 7%"}, session)+ assert out["status"] == "done", out+ out = _run(app_control.handle_do_in_app, {"action": "delete_memory", "id": f"decision:{decision_id}"}, session)+ assert out["status"] == "waiting_for_approval"+ assert client.post(f"/decisions/{out['decision_id']}/approve", json={}, headers=OWNER).status_code == 200+ assert _run(app_control.handle_find_in_app, {"kind": "memory"}, session)["items"] == []++[email protected]("kind", sorted(k for k, v in app_control.CATALOG.kinds.items() if not v.no_item))+def test_every_list_reads(kind: str, roster: dict[str, Any], monkeypatch: pytest.MonkeyPatch) -> None:+ from openexecutive.knowledge import store as knowledge_store++ class _Store:+ def __init__(self, *_a: Any, **_k: Any) -> None: ...++ def __getattr__(self, _name: str) -> Any:+ return lambda *_a, **_k: {}++ monkeypatch.setattr(knowledge_store, "ChromaDBStore", _Store)+ out = _run(app_control.handle_find_in_app, {"kind": kind}, _web(roster["owner"], "s-k"))+ assert "items" in out, out+++def test_topic_pin_merge_and_remove(roster: dict[str, Any]) -> None:+ owner = roster["owner"]+ session = _web(owner, "s-a")+ for sid, topic in (("s-a", "Leases"), ("s-b", "Lease terms")):+ _chat(owner.id, sid, sid)+ _run(app_control.handle_do_in_app, {"action": "move_chat_to_topic", "id": sid, "value": topic}, session)+ topics = {t["title"]: t["id"] for t in _run(app_control.handle_find_in_app, {"kind": "topic"}, session)["items"]}+ assert _run(app_control.handle_do_in_app, {"action": "pin_topic", "id": topics["Leases"]}, session)["status"] == "done"+ out = _run(app_control.handle_do_in_app,+ {"action": "merge_topic", "id": topics["Lease terms"], "value": "Leases"}, session)+ assert out == {"status": "done", "did": "Moved the chats in “Lease terms” into “Leases”"}, out+ out = _run(app_control.handle_do_in_app, {"action": "remove_topic", "id": topics["Leases"]}, session)+ assert out["status"] == "done", out+ assert _meta("s-a") is not None and _meta("s-b") is not None+++def test_settings_and_lead_rules(roster: dict[str, Any], client: TestClient) -> None:+ session = _web(roster["owner"], "s-s")+ out = _run(app_control.handle_do_in_app, {"action": "change_setting", "id": "delivery", "value": "digest"}, session)+ assert out == {"status": "done", "did": "Set How messages arrive (instant or digest) to digest"}, out+ out = _run(app_control.handle_do_in_app, {"action": "change_setting", "id": "act_as_me", "value": "off"}, session)+ assert out["status"] == "done", out+ out = _run(app_control.handle_do_in_app, {"action": "change_setting", "id": "act_as_me", "value": "on"}, session)+ assert out["status"] == "waiting_for_approval"+ out = _run(app_control.handle_do_in_app,+ {"action": "add_lead_rule", "id": "new", "value": "domain: acme.com"}, session)+ assert out["status"] == "done", out+ rules = _run(app_control.handle_find_in_app, {"kind": "lead_rule"}, session)["items"]+ assert [r["title"] for r in rules] == ["domain: acme.com"]+ out = _run(app_control.handle_do_in_app, {"action": "remove_lead_rule", "id": rules[0]["id"]}, session)+ assert out["status"] == "waiting_for_approval"+++def test_every_card_names_what_it_changes() -> None:+ # After outside content is read any action can become a card: each one+ # says which item and what new value, so the tap does what it shows.+ for action in app_control.CATALOG.actions.values():+ kind = app_control.CATALOG.kinds[action.kind]+ text = app_control.card_text(action, "Item X", "Value Y")+ if not kind.no_item:+ assert "Item X" in text, action.name+ if action.value:+ assert "Value Y" in text, action.name+++def test_a_shared_chat_gets_no_list_and_no_change(roster: dict[str, Any]) -> None:+ sid = _chat(roster["owner"].id, "s-shared", "Board prep")+ session = _web(roster["owner"], sid)+ session.shared_chat = True+ out = _run(app_control.handle_find_in_app, {"kind": "chat"}, session)+ assert "error" in out and "items" not in out+ out = _run(app_control.handle_do_in_app, {"action": "rename_chat", "id": sid, "value": "x"}, session)+ assert "error" in out+ assert (_meta(sid) or {})["title"] == "Board prep"+++def test_a_chat_turn_never_counts_as_a_signed_request() -> None:+ from openexecutive.api.caller import Caller+ from openexecutive.delegation import verified++ with verified.from_chat():+ assert verified.caller_refusal(Caller("user", "[email protected]"), "[email protected]") is not Nonediff --git a/packages/ui/src/components/ActionCards.tsx b/packages/ui/src/components/ActionCards.tsxindex 437da483..beac65b4 100644--- a/packages/ui/src/components/ActionCards.tsx+++ b/packages/ui/src/components/ActionCards.tsx@@ -3,6 +3,7 @@import { useCallback, useEffect, useState } from "react";import Button from "@/components/ui/Button";+import ChatAppActionCard from "@/components/ChatAppActionCard";import ChatMeetingCard from "@/components/ChatMeetingCard";import FeatureName from "@/components/FeatureName";import {@@ -209,8 +210,9 @@ export function ActionCardItem({export function ChatActionCards({ ids }: { ids: number[] }) {const { cards, loaded, gone } = useActionCards();const shown = cards.filter((c) => ids.includes(c.decision_id));- // Any other id is an approval of another kind (a meeting), shown by its own- // card once the action cards are known not to hold it.+ // Any other id is an approval of another kind (a meeting, something asked+ // for in chat), shown by its own card once the action cards are known not to+ // hold it. Each card shows only its own kind.const others = loaded ? ids.filter((id) => !cards.some((c) => c.decision_id === id)) : [];if (shown.length === 0 && others.length === 0) return null;return (@@ -219,7 +221,10 @@ export function ChatActionCards({ ids }: { ids: number[] }) {<ActionCardItem key={card.decision_id} card={card} onGone={gone} />))}{others.map((id) => (- <ChatMeetingCard key={id} id={id} />+ <div key={id}>+ <ChatMeetingCard id={id} />+ <ChatAppActionCard id={id} />+ </div>))}</div>);diff --git a/packages/ui/src/components/ChatAppActionCard.tsx b/packages/ui/src/components/ChatAppActionCard.tsxnew file mode 100644index 00000000..3f6e0a48--- /dev/null+++ b/packages/ui/src/components/ChatAppActionCard.tsx@@ -0,0 +1,109 @@+"use client";++import { useEffect, useState } from "react";+import { useRouter } from "next/navigation";++import Button from "@/components/ui/Button";+import {+ approveAppAction,+ getDecision,+ rejectDecision,+ type DecisionInstance,+} from "@/lib/api";++// The chat: something you asked the Executive to do in the app that waits+// for your OK (a delete, a share, turning on something that acts as you),+// shown under its reply. Confirm runs it with your own sign-in, through the+// same route as the button on its screen; Cancel drops it. Only you see it+// (the server answers anyone else 404), and a card left a day goes stale.++interface AppActionPayload {+ action: string;+ id: string;+ card: string;+}++function readPayload(instance: DecisionInstance): AppActionPayload | null {+ try {+ const raw = JSON.parse(instance.proposed_payload_json || "{}");+ if (typeof raw.card !== "string" || typeof raw.action !== "string") return null;+ return { action: raw.action, id: typeof raw.id === "string" ? raw.id : "", card: raw.card };+ } catch {+ return null;+ }+}++const DONE = new Set(["approved_unchanged", "approved_with_edit", "executed"]);++export default function ChatAppActionCard({ id }: { id: number }) {+ const router = useRouter();+ const [instance, setInstance] = useState<DecisionInstance | null>(null);+ const [busy, setBusy] = useState<string | null>(null);+ const [error, setError] = useState<string | null>(null);++ useEffect(() => {+ const controller = new AbortController();+ getDecision(id, controller.signal)+ .then(setInstance)+ .catch(() => { /* not this person's to see, or gone: the chip stays */ });+ return () => controller.abort();+ }, [id]);++ if (!instance || instance.decision_class !== "app_action") return null;+ const payload = readPayload(instance);+ if (!payload) return null;+ const done = DONE.has(instance.status);+ const waiting = instance.status === "proposed";+ if (!done && !waiting) return null;++ const confirm = async () => {+ setBusy("Doing it…");+ setError(null);+ try {+ const updated = await approveAppAction(instance.id);+ setInstance(updated);+ // Deleted the chat this card is in: there is nothing left to show here.+ if (payload.action === "delete_chat" && payload.id === instance.originating_session_id) {+ router.push("/?new=1");+ }+ } catch (err) {+ setError(err instanceof Error ? err.message : "That didn't go through.");+ } finally {+ setBusy(null);+ }+ };++ const cancel = async () => {+ setBusy("Cancelling…");+ setError(null);+ try {+ setInstance(await rejectDecision(instance.id));+ } catch (err) {+ setError(err instanceof Error ? err.message : "Couldn't cancel it.");+ } finally {+ setBusy(null);+ }+ };++ return (+ <article className="mt-3 rounded-2xl border border-line bg-surface-elevated p-4 sm:p-5">+ <div className="text-xs font-semibold uppercase tracking-wide text-accent">Needs your OK</div>+ <div className="mt-1 text-base sm:text-[17px] font-semibold leading-snug text-fg break-words">+ {payload.card}+ </div>+ {done ? (+ <p className="mt-3 text-sm font-semibold text-emerald-700 dark:text-emerald-300">✓ Done.</p>+ ) : (+ <div className="mt-4 flex flex-wrap items-center gap-2">+ <Button variant="primary" onClick={() => void confirm()} disabled={busy !== null}>+ {busy ?? "Confirm"}+ </Button>+ <Button variant="ghost" className="ml-auto" onClick={() => void cancel()} disabled={busy !== null}>+ Cancel+ </Button>+ </div>+ )}+ {error && <p className="mt-2 text-sm text-red-500">{error}</p>}+ </article>+ );+}diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.tsindex 7677e2f5..a9f9f768 100644--- a/packages/ui/src/lib/api.ts+++ b/packages/ui/src/lib/api.ts@@ -5466,6 +5466,21 @@ export async function rejectDecision(return res.json();}+// Confirm something asked for in chat (an app_action card): the route says+// why in words when it can't be done, and that is what the card shows.+export async function approveAppAction(id: number): Promise<DecisionInstance> {+ const res = await fetch(`${API_BASE}/decisions/${id}/approve`, {+ method: "POST",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({ edits: null }),+ });+ if (!res.ok) {+ const body = (await res.json().catch(() => ({}))) as { detail?: unknown };+ throw new Error(typeof body.detail === "string" ? body.detail : "That didn't go through.");+ }+ return res.json();+}+// ── Client-company slots (fractional / multi-client mode) ──────────────────