Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

feat(chat): fold messages sent mid-turn into the running answer (#352)

Rufusbba990f20dab
diff --git a/packages/core/openexecutive/api/models.py b/packages/core/openexecutive/api/models.py
index abb1efe0..91b43c48 100644
--- a/packages/core/openexecutive/api/models.py
+++ b/packages/core/openexecutive/api/models.py
@@ -85,6 +85,19 @@ class StopChatRequest(BaseModel):
)
+class AddChatMessageRequest(BaseModel):
+ """Body of POST /chat/add — a message for a turn that is still running."""
+
+ client_turn_id: str = Field(
+ ..., min_length=8, max_length=64, pattern=r"^[A-Za-z0-9-]+$"
+ )
+ # Client-minted, echoed back in the stream's `message_added` event.
+ message_id: str = Field(
+ ..., min_length=8, max_length=64, pattern=r"^[A-Za-z0-9-]+$"
+ )
+ message: str = Field(..., min_length=1, max_length=32000)
+
+
class ChatResponse(BaseModel):
response: str
session_id: str
diff --git a/packages/core/openexecutive/api/routes/chat.py b/packages/core/openexecutive/api/routes/chat.py
index 29ec2a0d..df07b14d 100644
--- a/packages/core/openexecutive/api/routes/chat.py
+++ b/packages/core/openexecutive/api/routes/chat.py
@@ -15,12 +15,18 @@ from fastapi import APIRouter, File, Form, HTTPException, Request, UploadFile
from fastapi.responses import StreamingResponse
from openexecutive.api import caller as api_caller
-from openexecutive.api.models import ChatRequest, PageContext, StopChatRequest
+from openexecutive.api.models import (
+ AddChatMessageRequest,
+ ChatRequest,
+ PageContext,
+ StopChatRequest,
+)
from openexecutive.audit import log_event as audit_log
from openexecutive.audit import principal_turn_rows, rows_for_person
from openexecutive.integrations.attachments import build_attachment_output
from openexecutive.orchestrator.answer_sources import TurnSources
from openexecutive.orchestrator.debug_events import DebugCollector
+from openexecutive.orchestrator.turn_inbox import TurnInbox
# Per-file size cap. Mirrors `_DEFAULT_MAX_BYTES` in
# `openexecutive/integrations/attachments.py` so the web chat behaves the same
@@ -98,6 +104,9 @@ class _StopEntry(NamedTuple):
# Monotonic registration time, used to reclaim entries stranded by a path
# that never reaches `_sse_body`'s `finally`.
started_at: float
+ # Messages the owner sends while this turn runs (POST /chat/add), folded
+ # into the turn at its next step. See `orchestrator.turn_inbox`.
+ inbox: TurnInbox | None = None
# client_turn_id -> stop switch for every currently-streaming chat turn. Same
@@ -242,7 +251,7 @@ def _register_stop(
return None
event = asyncio.Event()
_active_stops[client_turn_id] = _StopEntry(
- event, owner, turn_id, time.monotonic()
+ event, owner, turn_id, time.monotonic(), TurnInbox()
)
return event
@@ -375,6 +384,75 @@ def _request_stop(client_turn_id: str, owner: str) -> str | None:
return entry.turn_id
+def _add_to_turn(client_turn_id: str, owner: str, message_id: str, text: str) -> str | None:
+ """Hand a message to a running turn's inbox. Returns its server
+ `turn_id`, or None.
+
+ None covers "no such live turn", "not yours" and "the turn won't take it
+ any more" alike, for the same reason as `_request_stop`; the client then
+ sends the message as the next turn.
+ """
+ entry = _active_stops.get(client_turn_id)
+ if entry is None or entry.owner != owner or entry.inbox is None:
+ return None
+ if entry.event.is_set() or not entry.inbox.add(message_id, text):
+ return None
+ return entry.turn_id
+
+
+# One turn at a time per conversation. A second /chat on a conversation that
+# is still answering (another tab, a retry) waits for the first to finish and
+# persist, rather than running beside it on the same history. The web chat's
+# own box never sends one: a message typed mid-turn goes to POST /chat/add.
+_session_turn_locks: dict[str, asyncio.Lock] = {}
+# How many turns hold or wait on each conversation's lock. An idle lock is
+# dropped only at zero: `release()` wakes the next waiter but `locked()` reads
+# False until it runs, so "not locked" alone would drop a lock someone still
+# queues on, and the next turn would make a fresh one and run beside them.
+_session_turn_users: dict[str, int] = {}
+
+
+async def _acquire_session_turn(session_id: str, timeout_s: float) -> asyncio.Lock | None:
+ """Wait for this conversation's turn lock; None if the wait timed out.
+
+ Bounded so a turn stranded holding the lock (a path that never reaches
+ `_sse_body`'s `finally`) can't wedge the conversation for good: past the
+ deadline the turn runs anyway, as every turn did before the lock.
+ """
+ lock = _session_turn_locks.get(session_id)
+ if lock is None:
+ lock = asyncio.Lock()
+ _session_turn_locks[session_id] = lock
+ _session_turn_users[session_id] = _session_turn_users.get(session_id, 0) + 1
+ try:
+ await asyncio.wait_for(lock.acquire(), timeout=timeout_s)
+ except BaseException as exc:
+ _leave_session_turn(session_id)
+ if isinstance(exc, TimeoutError):
+ logger.warning("chat.session_lock_timeout session_id=%s", session_id)
+ return None
+ raise
+ return lock
+
+
+def _leave_session_turn(session_id: str) -> None:
+ left = _session_turn_users.get(session_id, 1) - 1
+ if left > 0:
+ _session_turn_users[session_id] = left
+ return
+ # Nobody holds or waits on it: drop it so the maps track live
+ # conversations only.
+ _session_turn_users.pop(session_id, None)
+ _session_turn_locks.pop(session_id, None)
+
+
+def _release_session_turn(session_id: str, lock: asyncio.Lock | None) -> None:
+ if lock is None or not lock.locked():
+ return
+ lock.release()
+ _leave_session_turn(session_id)
+
+
# Who started each chat this process has served. Lets a caller the roster
# can't resolve (a fresh install with no principal yet, or an allowlisted user
# who isn't on the roster) keep talking in a chat they started, without opening
@@ -775,6 +853,9 @@ async def _run_chat_turn(
client_turn_id = None
else:
logger.info("chat.stop_registered turn_id=%s", turn_id)
+ inbox: TurnInbox | None = (
+ _active_stops[client_turn_id].inbox if client_turn_id else None
+ )
# Guarded for the same reason as the gather further down: the stop switch
# is already registered, and `_sse_body`'s `finally` — which normally
@@ -783,10 +864,27 @@ async def _run_chat_turn(
# that no longer parses, or a locked SQLite DB), and a stranded entry is
# now permanent-ish: the registry refuses new turns at its cap rather than
# evicting live ones, so enough of them would disable Stop for everybody.
+ # Wait for any turn still answering in this conversation, so this one
+ # loads its finished history. A fresh chat has nobody to wait for.
+ turn_lock: asyncio.Lock | None = None
+ lock_key = requested_id
+ if lock_key is not None:
+ from openexecutive.config import get_settings as _lock_settings
+
+ _ls = _lock_settings()
+ try:
+ turn_lock = await _acquire_session_turn(
+ lock_key, _ls.chat_stream_timeout_s + _ls.committee_extra_timeout_s
+ )
+ except BaseException:
+ _release_stop(client_turn_id, turn_id)
+ raise
try:
session = _get_or_create_session(requested_id, request)
except BaseException:
_release_stop(client_turn_id, turn_id)
+ if lock_key is not None:
+ _release_session_turn(lock_key, turn_lock)
raise
if access == "missing":
_session_starters.setdefault(
@@ -995,6 +1093,8 @@ async def _run_chat_turn(
timeout_s += settings.committee_extra_timeout_s
except BaseException:
_release_stop(client_turn_id, turn_id)
+ if lock_key is not None:
+ _release_session_turn(lock_key, turn_lock)
raise
async def event_generator():
@@ -1037,6 +1137,9 @@ async def _run_chat_turn(
)
full_response = ""
+ # Messages folded into this turn (POST /chat/add), filled once the
+ # turn's inbox closes and persisted with it.
+ added_texts: list[str] = []
# Row id of the persisted assistant reply, handed to the client on
# `done` so it can attach 👍/👎 without a second roundtrip.
persisted: dict[str, int] = {}
@@ -1068,6 +1171,7 @@ async def _run_chat_turn(
turn_id=turn_id,
memory_text=memory_text,
turn_sources=turn_sources,
+ inbox=inbox,
).__aiter__()
else:
stream = executive.stream_chat(
@@ -1084,6 +1188,7 @@ async def _run_chat_turn(
turn_id=turn_id,
memory_text=memory_text,
turn_sources=turn_sources,
+ inbox=inbox,
).__aiter__()
# Whole-turn deadline, not per-chunk: a stream that drips bytes
@@ -1128,6 +1233,13 @@ async def _run_chat_turn(
save_message(
session.session_id, "user", message, sender_person_id=caller_person_id
)
+ # Messages sent while it worked and folded into this reply,
+ # in the order they arrived, before the reply that answers
+ # them.
+ for added_text in added_texts:
+ save_message(
+ session.session_id, "user", added_text, sender_person_id=caller_person_id
+ )
persisted["assistant_message_id"] = save_message(
session.session_id,
"assistant",
@@ -1146,6 +1258,8 @@ async def _run_chat_turn(
# never happened, while a page reload showed it.
if stopped or client_disconnected or timed_out:
session.add_user_message(message)
+ for added_text in added_texts:
+ session.add_user_message(added_text)
session.add_assistant_message(full_response)
logger.info(
"chat.turn_persisted turn_id=%s is_first_turn=%s disconnected=%s stopped=%s",
@@ -1287,6 +1401,25 @@ async def _run_chat_turn(
# Otherwise: "Task was destroyed but it is pending".
stop_waiter.cancel()
+ # Nothing more can reach this turn: anything still waiting in the
+ # inbox was never seen, and the client sends it as the next turn.
+ if inbox is not None:
+ inbox.close()
+ added_texts.extend(inbox.taken_texts())
+ # Audited like the turn's own "User:" row: private, and the
+ # caller's own, in a conversation that read their mail.
+ with rows_for_person(caller_person_id) if kept_private else contextlib.nullcontext():
+ for added_text in added_texts:
+ audit_log(
+ "chat_turn",
+ f"User (added while working): {added_text[:200]}",
+ session_id=session.session_id,
+ turn_id=turn_id,
+ actor="user",
+ details={"direction": "in", "added_mid_turn": True, "msg_len": len(added_text)},
+ full={"message": added_text},
+ )
+
logger.info(
"chat.executive_done turn_id=%s chunks=%d duration_s=%.2f timed_out=%s disconnected=%s stopped=%s",
turn_id, chunk_count, time.monotonic() - exec_t0, timed_out,
@@ -1386,7 +1519,11 @@ async def _run_chat_turn(
done = json.dumps({"type": "done", "session_id": session.session_id})
yield f"data: {done}\n\n"
finally:
+ if inbox is not None:
+ inbox.close()
_release_stop(client_turn_id, turn_id)
+ if lock_key is not None:
+ _release_session_turn(lock_key, turn_lock)
return StreamingResponse(
event_generator(),
@@ -1437,6 +1574,36 @@ async def chat_stop(body: StopChatRequest, request: Request) -> dict[str, str]:
return {"status": "stopping", "turn_id": stopped_turn_id}
[email protected]("/chat/add")
+async def chat_add(body: AddChatMessageRequest, request: Request) -> dict[str, str]:
+ """Add a message to an in-flight /chat turn, addressed by its
+ `client_turn_id`, while the Executive is still working on it.
+
+ The turn takes it at its next step and the stream names it in a
+ `message_added` event. 404 means the turn won't take it (finished,
+ stopped, full, or not yours, indistinguishably); the client then sends it
+ as the next turn. A message the turn accepted but never reached (it was
+ already writing its final answer) is not named in any `message_added`
+ event, and the client sends that one as the next turn too.
+ """
+ client_turn_id = _clean_client_turn_id(body.client_turn_id)
+ message_id = _clean_client_turn_id(body.message_id)
+ turn_id = (
+ _add_to_turn(
+ client_turn_id,
+ _stop_owner_key(request, _resolve_caller_person_id(request)),
+ message_id,
+ body.message,
+ )
+ if client_turn_id and message_id
+ else None
+ )
+ if turn_id is None:
+ raise HTTPException(status_code=404, detail="No in-flight turn with that id")
+ logger.info("chat.message_added turn_id=%s len=%d", turn_id, len(body.message))
+ return {"status": "added", "turn_id": turn_id}
+
+
@router.post("/chat/upload")
async def chat_upload(
request: Request,
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index 33df4449..bac3989d 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -4397,7 +4397,7 @@ today:
chat:
module: openexecutive.api.routes.chat
- endpoint: POST /chat — server-sent events stream of the live turn. POST /chat/stop halts one mid-flight.
+ endpoint: POST /chat — server-sent events stream of the live turn. POST /chat/stop halts one mid-flight. POST /chat/add hands it a message the person typed while it works.
sse_event_types:
- "chunk — one text delta from the assistant response stream. Fields: type, content, session_id."
- "thinking — keepalive emitted at the start of EVERY tool-use round, not just specialist ones. Fields: type, session_id. It carries no tool information, so the UI uses it purely as an in-flight boolean and takes the wording from the `activity` event that immediately precedes it. It used to be the sole driver of a hardcoded 'Consulting specialists…' string, which is why an MCP or calendar round looked like a specialist fan-out."
@@ -4409,8 +4409,35 @@ chat:
- "form_patch — emitted when the Executive calls `propose_form_values` (Ask OE panel form-fill tier). Fields: type, form_id, fields (name → proposed value map), rationale, iteration. The panel applies the values into the registered on-screen form as highlighted suggestions; nothing is saved server-side and the user submits through the form's normal Save. NOT persisted with the assistant message (same deferred-persistence bucket as the action-chip note below predating chip persistence) — reopening a panel session loses the proposal cards, though values already applied to a form are unaffected."
- "stopped — the user halted the turn via POST /chat/stop. Carries type + session_id. ALWAYS followed by `done` over the same still-open stream: the server winds the turn down and reports, rather than the connection simply dying, so a consumer's state machine reaches its normal terminal state and there is no abort path to special-case. Deliberately NOT an `error` — a stop is a user decision, not a failure — so a consumer that ignores the event degrades to 'the turn ended normally', which is the safe reading. Whatever the Executive produced before the stop is persisted and flagged (chat_messages.stopped)."
- "sources — sent by the route once per turn after the reply, also when it was stopped or timed out, before the stopped / error / done frames; only when the reply has text and the turn looked at something or had to leave an area out. Fields: type, session_id, sources ([{kind: company|knowledge|notion|research|document|web, title, url: http(s), /artifacts/<id> for a document, or null}], ≤12, ≤6 web, cited pages first), unavailable ([area], e.g. \"finance\" — never a specialist name). Persisted as chat_messages.sources; see routing.answer_sources."
+ - "message_added — the running turn took messages the person sent while it worked (POST /chat/add). Fields: type, ids (the client-minted message ids). Emitted by the agent loop at the step boundary where it took them. A message the client queued that no `message_added` names was never seen, and the client sends it as the next turn."
- "done — final marker carrying the resolved session_id; UI uses this to commit the streamed assistant message and clear the pending-prompt state."
- "error — terminal error before/after streaming. Always followed by `done` so the stream consumer's state-machine reaches a clean end."
+ added_messages: |
+ The chat box stays open while the Executive works. A message typed then
+ goes to `POST /chat/add` with the turn's `client_turn_id` and a
+ client-minted message id, not to a second /chat. Each stop-registry
+ entry carries a `TurnInbox` (orchestrator/turn_inbox.py); the endpoint
+ checks the same owner key as /chat/stop, with the same 404 for unknown,
+ not yours, stopped or closed. The agent loop takes whatever arrived at
+ each step boundary (after a round's tool results, before the next model
+ call) and appends it as a text block after the tool_result blocks, so the
+ answer it is writing follows the newer message, and the cached prefix is
+ untouched. A message arriving while the final answer is written is never
+ taken: the route closes the inbox when the turn ends and the client sends
+ leftovers as the next turn. Taken messages are audited as the person's
+ words, persisted as their own user rows between the turn's message and
+ its reply, mirrored into the live Session, and fed to the memory passes
+ with the turn's own words. `_build_messages` merges consecutive user
+ history rows so the prompt still alternates. A stop before any output
+ saves none of it, and the UI returns everything to the composer.
+
+ One turn at a time per conversation: `_run_chat_turn` takes a
+ per-session asyncio.Lock (`_session_turn_locks`) before loading the
+ session, so a second /chat on the same conversation (another tab, a
+ retry) waits for the first to finish and persist instead of running on
+ the same history. The wait is bounded by the whole-turn deadline; past
+ it the turn runs anyway, so a stranded lock can't wedge a conversation.
+ Single-process, like the stop registry.
stop_control: |
The Stop button. The CLIENT mints a `client_turn_id` (uuid4) and sends it
with the turn; `POST /chat/stop` takes that id and sets an asyncio.Event
diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.json
index 2bad7c5a..e8f99a39 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). 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 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 configured UI origins. 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` | SSE stream of a live Executive turn. 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/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller. 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. 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. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/top-three`, `GET /today/weekly-review` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). `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`, `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` | Department state and per-department goals. `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). 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}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `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` and `supersedes_id` on every summary. `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), 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/signature`, `PUT /delegation/inbox`, `POST /delegation/inbox/check`, `GET /delegation/replies`, `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}, 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/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), 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. 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`. 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}` (`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). `PUT` turns notes on only for someone who may keep them (403 `not_available`), 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| `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). 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 list, its `total` and the usage totals leave them out, a private row's id is a 404, and a session shows only its other rows. |\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 (unauthenticated). |\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}]}`); `/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}` — `held_actions` counts due `pending` rows that fire on resume. `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`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. 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` and `background` (true for the system-run built-ins the UI files under “System”). 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| `skill_drafts` | `/skill-drafts`, `/skill-drafts/{name}`, `/skill-drafts/{name}/approve` | Review queue for playbook changes the Executive proposed from chat. `GET` lists drafts (`action` create / update / delete, the proposed fields, an `id` version token, `current` — the playbook in effect now — and `followers`, the workflows that follow the name); `approve` (body `{id}`) applies exactly the reviewed version through the ordinary skills operations — 409 and the draft is kept if it was replaced since, on a conflict, or if its playbook vanished; `DELETE ?id=` discards that version only. |\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/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/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). `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/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard. 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| `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. |\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` | Inbound integration callbacks (self-verified). |\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. See the MCP Server section. |",
+ "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). 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 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 configured UI origins. 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` | SSE stream of a live Executive turn. `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. 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/{id}`, `GET /sessions/{id}/messages`, `DELETE /sessions/{id}`, `POST /sessions/{id}/messages/{message_id}/feedback`, `GET /sessions/{id}/followup` | List, read and delete saved chat sessions (assistant messages carry their row `id` and any `feedback`). The list is scoped to the caller. 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. 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. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily`, `GET /today/brief-delivery`, `GET /today/top-three`, `GET /today/weekly-review` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). `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`, `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` | Department state and per-department goals. `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). 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}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `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` and `supersedes_id` on every summary. `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), 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/signature`, `PUT /delegation/inbox`, `POST /delegation/inbox/check`, `GET /delegation/replies`, `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}, 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/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), 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. 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`. 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}` (`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). `PUT` turns notes on only for someone who may keep them (403 `not_available`), 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| `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). 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 list, its `total` and the usage totals leave them out, a private row's id is a 404, and a session shows only its other rows. |\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 (unauthenticated). |\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}]}`); `/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}` — `held_actions` counts due `pending` rows that fire on resume. `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`, `GET /workflows/tools/search?q=`, `GET /workflows/tools/describe?names=` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. 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` and `background` (true for the system-run built-ins the UI files under “System”). 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| `skill_drafts` | `/skill-drafts`, `/skill-drafts/{name}`, `/skill-drafts/{name}/approve` | Review queue for playbook changes the Executive proposed from chat. `GET` lists drafts (`action` create / update / delete, the proposed fields, an `id` version token, `current` — the playbook in effect now — and `followers`, the workflows that follow the name); `approve` (body `{id}`) applies exactly the reviewed version through the ordinary skills operations — 409 and the draft is kept if it was replaced since, on a conflict, or if its playbook vanished; `DELETE ?id=` discards that version only. |\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/start`, `/onboard/interview/message`, `/onboard/interview/draft`, `/onboard/interview/{id}`, `/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). `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/message`, `POST /workflows/designer/draft`, `GET /workflows/designer/{session_id}` | The conversational New workflow wizard. 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| `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. |\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` | Inbound integration callbacks (self-verified). |\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. See the MCP Server section. |",
"mermaid": null,
- "generated_at": "2026-10-03T17:00:00Z"
+ "generated_at": "2026-10-03T20:14:36Z"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/lifecycle.json b/packages/core/openexecutive/architecture/prebuilt/lifecycle.json
index dc244288..fe4a9310 100644
--- a/packages/core/openexecutive/architecture/prebuilt/lifecycle.json
+++ b/packages/core/openexecutive/architecture/prebuilt/lifecycle.json
@@ -1,7 +1,7 @@
{
"section_id": "lifecycle",
"title": "Request Lifecycle",
- "markdown": "A single chat message makes a full round-trip through the API, the orchestrator's tool-use loop, a parallel specialist fan-out, and synthesis — all streamed back as server-sent events.\n\n### Steps\n\n1. **Arrival** — the client mints a `client_turn_id` and posts to `POST /chat` (`openexecutive.api.routes.chat`). The turn carries a `<current_speaker>` hint resolved from the caller's `person_id` (followed by that person's `<working_style>` rules when they have any — see the attunement section), plus a `<briefing>` digest of current open alerts (built in parallel with RAG/episodic/peer-memory fetches) so the Executive can discuss any item shown on the `/today` briefing page. A turn arriving from a chat adapter instead of the web app also carries a `<channel>` block naming the surface and stating which approvals can be completed there; on Slack the `<briefing>` digest is gated to the principal's DMs. All three ride in the **user turn**, never a cached system block, as does a `<drive_memory>` block naming the Drive files this conversation already found or opened and the Drive searches that matched nothing (see the memory section). The server registers a stop switch under that id *before* the context fetch, so a Stop pressed during those first seconds halts the turn before any model call is made.\n2. **Tool-use loop** — the `Executive` calls Claude. For a cross-domain question the assistant turn emits multiple `consult_specialist` tool-use blocks at once.\n3. **Parallel fan-out** — `openexecutive.orchestrator.router.route_parallel` dispatches those calls concurrently, bounded by `MAX_PARALLEL_SPECIALISTS`; calls past the cap get a skip tool_result. A specialist that raises (a timeout, an overloaded model) or returns no text no longer fails the batch: its tool_result says it is unavailable and tells the Executive not to invent its view, the others' results stand, and the turn goes on. It does not count as consulted, so it takes no committee seat and no department memory records the turn, and its documents are left out of the answer's sources. On the web chat the reply need not mention the gap, because the app shows it under the answer; on every other channel the tool_result asks the Executive to say in one sentence that part of the analysis is missing. A knowledge retrieval that fails likewise leaves that specialist without context rather than failing the turn.\n4. **Per-specialist RAG** — each specialist runs its own domain-filtered ChromaDB query, then reasons over the retrieved chunks and returns analysis as a tool_result. Its user turn also carries a `<company_stage>` tag from the session's company profile, so stage-sensitive advice (venture benchmarks vs. cash-first for a bootstrapped company) does not depend on the Executive remembering to mention it. Once the batch is done, the documents each answering specialist's retrieval returned are named, in call order, into the turn's `TurnSources` (`orchestrator/answer_sources.py`), which the web chat route owns and which also holds its own search's documents. Synced Google Drive files are recorded as `drive` sources with their Drive link, and the web chat lists them under **Google Drive**.\n5. **Synthesis** — the Executive feeds the tool_results back to Claude and streams one coherent reply. Every tool round — not just a specialist one — emits an `activity` event naming what is running, immediately followed by a `thinking` keepalive. The label names the *activity*, never the internal agent: \"Putting time on the calendar…\", \"Looking up people…\", or, for an MCP call, the underlying tool by name. A round that really does fan out collapses to the generic \"Consulting specialists…\" — the one voice holds even in the progress line. The keepalive carries no tool information of its own; it used to drive a hardcoded \"Consulting specialists…\" string, so an MCP or calendar round misreported itself as a fan-out.\n6. **Optional committee review** — when enabled, `Executive.stream_chat_with_committee()` runs a silent draft, parallel reviewer critiques, then a streamed revision pass.\n7. **Side effects** — after the reply, every rostered speaker's turn (not only the principal's) schedules a fire-and-forget **open-loop pass** (Attunement) beside the episodic extraction: a keyword prefilter, then one forced-tool call that may open or close loops, every item quote-gated against the speaker's own words. The user message is persisted with `sender_person_id` — the resolved speaker, never the principal fallback a Discord / Telegram session uses for ownership — and the session records the speaker for the turn (`Session.caller_person_id`), which `close_open_loop` reads. A DM sent while proactive work is tagged (`attunement.outcomes.tag_proactive` — scheduler dispatch, reflection, research, alert review) also opens an outcome-ledger row at `_record_outbound_context`; a user's own turn is never tagged. Any side-effecting tool call surfaces an `action_taken` chip, which unlike the ephemeral `activity` label is persisted with the assistant message; once the reply is over — also when it was stopped or timed out — the web chat route sends one `sources` event: the documents and web pages the turn looked at (its own search, each specialist that answered, web search results, and the pages the reply cites, which are always kept) and the areas (\"finance\", never a specialist) it had to go without. The web chat shows it under the reply, and it is persisted with the assistant message as `chat_messages.sources`; other channels don't collect it. The stream closes with a `done` event — preceded by a `stopped` event when the user halted the turn, in which case the partial reply is still persisted and flagged so it reads as cut short rather than complete, and is mirrored into the live in-memory session so the next turn's prompt matches what was saved. The stream still ends with `done` event. One side-effecting tool is gated server-side rather than by its description: `ack_alert` will only accept an `alert_id` from the live alert board the server itself derived this turn — the whole live set, not only the rows the `<briefing>` digest printed, since `/today` renders more cards than the digest lists and every one of them is Discuss-able — and it fails closed, so an id it cannot even parse is refused rather than waved through to the handler's own parse. That check runs on **every** session. It used to run only on turns that arrived from a chat channel, keyed on `origin_channel`, which the browser never sets — so the web, the surface the principal actually uses, was unchecked and the model could ack any id, including one quoted out of an alert body by the briefing page's Discuss handoff. What that buys is bounded and worth stating plainly: an id that is invented, closed, snoozed or expired is refused, including one quoted out of an attacker-written alert body; the model being argued into acking the wrong *live* card is not prevented. The one way to widen that set is `find_alerts`, for an item the principal names that has left the live board (already opened, snoozed, older than the board): a keyword search over alerts of every status whose own results — never an id the model supplies — join the trusted set. It runs only in a turn where `render_and_trust` showed the principal their own board (`Session.principal_board_shown`: the verified principal, and on a channel only in their DM), never merely because the session has a set — every `Session` starts with an empty one, and that empty set is how a Google Chat turn, someone else's DM or an unattended pass refuses every ack — and not on the principal's turn in a shared Slack or Discord thread either, where others read the reply and write into what the model reads. It trusts only rows still open (`unread`, `read`), never a roster-request card, and at most 25 ids per turn across calls, and refuses a query with no word of three or more letters. It also moves the admitted limit outward: a model argued into the wrong search can now reach up to 25 open alerts that are off the board, not only live ones. The board is recorded on the turn's `Session`, and the route binds that session for the **whole** SSE body (`schedule_tools.set_session`, alongside `set_turn`) rather than letting `stream_chat` bind it from inside its own generator. `_sse_body` drives the executive with `asyncio.wait_for(stream.__anext__())`, which runs each step in a fresh Task holding a *copy* of the context, so a binding made inside the generator is discarded with the step that made it: step one sees the session and every later step sees `None`. The tool-call loop runs on those later steps, so the whole guard read an empty set and refused every ack on the web — on live, open cards — until the binding moved out to the route. Anything reading `current_session` mid-turn has the same requirement, and two of them needed more than the binding to behave. `schedule_followup`'s seen-`channel_ref` anti-spam gate refuses a send to an address the session has not seen; with no session it skipped itself, so a web turn could schedule to **any** address, and with an empty one it refused even the principal's own. The route now seeds the caller's own addresses onto the session, so on web the gate means what it means on every other surface. Reply linkage (`_record_outbound_context`, read back by `inbound_hydration` to quote the originating conversation into the turn handling a recipient's reply) is the other: it was never reachable on web, and rather than switch that on for the principal's broadest surface as a side effect it is held back, keyed on an explicit `Session.from_web_chat` flag. Not on an empty `origin_channel` — alert review, the CLI and the unattended workflows all leave it empty while legitimately recording linkage, as does the email poller under its own `email` tag. `scheduled_actions` rows also take their `session_id` from the session. A session that was shown no board has an empty trusted set and can ack nothing, so the unattended passes (the nightly reflection, the research synthesis) are refused by default — they also still withhold the tool outright, which is belt-and-braces rather than the only thing stopping them. After the stream closes, the turn is also handed to the episodic memory extractor (`memory.episodic.schedule_extraction`, fire-and-forget) — on every turn where the principal said anything at all, and only the principal: a turn naming an `origin_channel` must resolve to a person marked `is_principal`, because the quote validator downstream cannot tell whose words it is checking. Both this path and the committee path call the same `should_extract` predicate, and it applies no length floor: the gate used to sum in the assistant's reply, which let a verbose answer drag a trivial turn in and discarded the short, decisive instructions that are the whole point of extracting. A user-side floor would fare no better — \"Do B.\" and \"Done\" are one character apart. See **Memory** for what that cost on a live tenant.\n8. **Tool failures** — a handler that raises instead of returning its JSON error is isolated: both tool gathers run with `return_exceptions=True`, the model gets an error `tool_result` naming only the exception's TYPE — a message can carry a filesystem path, a validation error echoing the input, or a third-party HTTP body, and anything in model context can be quoted back to the user, so the full repr stays in the log and the audit row — and the failure is audited with `ok=false`. Only `CancelledError` is re-raised, so turn-timeout and client-disconnect handling still work. Before this one crashing tool aborted the whole turn, which reached the user as an unexplained apology with no audit row (#136).\n\nWeb search, when invoked on the Anthropic path, executes inside the Anthropic API itself (`web_search_20250305`) and returns within the same generation; for any model routed via OpenRouter the same tool becomes OpenRouter's `openrouter:web_search` server tool, which also runs inside the generation with the same search cap and domain lists.\n\nThe install's workspace mode (solo or team, see Org) is read fresh at the start of each turn by `memory.workspace_settings.pin_turn_workspace_mode(session)` and pinned on the session for that turn only (`Session.turn_workspace_mode`): the persona, the org block, the tool list and every tool handler in the turn then agree, and a switch made mid-turn applies from the next turn. A session can instead carry an explicit override, `Session.workspace_mode` (`None` by default), which wins over both — so a caller that runs many conversations concurrently on one Executive, such as evals, can pick the mode per session rather than flipping the install-wide setting. Everything reads it through `effective_workspace_mode(session)` (override, then the turn's pin, then the setting). The principal's role is pinned the same way (`pin_turn_principal_role(session, mode)` → `Session.turn_principal_role`: in solo the `Session.principal_role` override, else the workspace settings read fresh; in team an empty role). The org block renders it, each specialist batch gets it as a `<principal_role>` user-turn tag, and a workflow the turn starts reads the same pin through `effective_principal_role` (override, then the pin, then the setting), so a role edited mid-turn applies from the next turn; a team turn sends none.\n\nAct as me is pinned beside them: `delegation.settings.pin_turn_delegation(session, speaker_text)` records on `Session.turn_delegation` whether the speaker has it on, whether `ghostwrite_email` is offered this turn (the principal, or a team member once the owner lets them, on a verified surface, in a conversation private to them, attended), and the speaker's own words. The pin is also held in a context variable for the turn's task, so two turns running at once on one session each read their own. The tool list, the tool handler and the turn's audit privacy all read that one pin, so a switch flipped mid-turn applies from the next turn. Once the tool touches the speaker's mailbox, the conversation is the speaker's alone (`session_store.mark_mail_private`, the principal included when it isn't theirs), the rest of the turn's audit rows are private (a team member's theirs alone) and the turn teaches no memory: no extraction, open-loop, working-style or Honcho pass runs on it.",
+ "markdown": "A single chat message makes a full round-trip through the API, the orchestrator's tool-use loop, a parallel specialist fan-out, and synthesis — all streamed back as server-sent events.\n\n### Steps\n\n1. **Arrival** — the client mints a `client_turn_id` and posts to `POST /chat` (`openexecutive.api.routes.chat`). The turn carries a `<current_speaker>` hint resolved from the caller's `person_id` (followed by that person's `<working_style>` rules when they have any — see the attunement section), plus a `<briefing>` digest of current open alerts (built in parallel with RAG/episodic/peer-memory fetches) so the Executive can discuss any item shown on the `/today` briefing page. A turn arriving from a chat adapter instead of the web app also carries a `<channel>` block naming the surface and stating which approvals can be completed there; on Slack the `<briefing>` digest is gated to the principal's DMs. All three ride in the **user turn**, never a cached system block, as does a `<drive_memory>` block naming the Drive files this conversation already found or opened and the Drive searches that matched nothing (see the memory section). The server registers a stop switch under that id *before* the context fetch, so a Stop pressed during those first seconds halts the turn before any model call is made.\n2. **Tool-use loop** — the `Executive` calls Claude. For a cross-domain question the assistant turn emits multiple `consult_specialist` tool-use blocks at once.\n The person can keep typing while it works. A message sent then (`POST /chat/add`) joins the running turn: the loop adds it after the next round's tool results, so the answer follows it, and it is saved as its own message before the reply. One that arrives while the final answer is being written becomes the next turn instead. A conversation runs one turn at a time.\n3. **Parallel fan-out** — `openexecutive.orchestrator.router.route_parallel` dispatches those calls concurrently, bounded by `MAX_PARALLEL_SPECIALISTS`; calls past the cap get a skip tool_result. A specialist that raises (a timeout, an overloaded model) or returns no text no longer fails the batch: its tool_result says it is unavailable and tells the Executive not to invent its view, the others' results stand, and the turn goes on. It does not count as consulted, so it takes no committee seat and no department memory records the turn, and its documents are left out of the answer's sources. On the web chat the reply need not mention the gap, because the app shows it under the answer; on every other channel the tool_result asks the Executive to say in one sentence that part of the analysis is missing. A knowledge retrieval that fails likewise leaves that specialist without context rather than failing the turn.\n4. **Per-specialist RAG** — each specialist runs its own domain-filtered ChromaDB query, then reasons over the retrieved chunks and returns analysis as a tool_result. Its user turn also carries a `<company_stage>` tag from the session's company profile, so stage-sensitive advice (venture benchmarks vs. cash-first for a bootstrapped company) does not depend on the Executive remembering to mention it. Once the batch is done, the documents each answering specialist's retrieval returned are named, in call order, into the turn's `TurnSources` (`orchestrator/answer_sources.py`), which the web chat route owns and which also holds its own search's documents. Synced Google Drive files are recorded as `drive` sources with their Drive link, and the web chat lists them under **Google Drive**.\n5. **Synthesis** — the Executive feeds the tool_results back to Claude and streams one coherent reply. Every tool round — not just a specialist one — emits an `activity` event naming what is running, immediately followed by a `thinking` keepalive. The label names the *activity*, never the internal agent: \"Putting time on the calendar…\", \"Looking up people…\", or, for an MCP call, the underlying tool by name. A round that really does fan out collapses to the generic \"Consulting specialists…\" — the one voice holds even in the progress line. The keepalive carries no tool information of its own; it used to drive a hardcoded \"Consulting specialists…\" string, so an MCP or calendar round misreported itself as a fan-out.\n6. **Optional committee review** — when enabled, `Executive.stream_chat_with_committee()` runs a silent draft, parallel reviewer critiques, then a streamed revision pass.\n7. **Side effects** — after the reply, every rostered speaker's turn (not only the principal's) schedules a fire-and-forget **open-loop pass** (Attunement) beside the episodic extraction: a keyword prefilter, then one forced-tool call that may open or close loops, every item quote-gated against the speaker's own words. The user message is persisted with `sender_person_id` — the resolved speaker, never the principal fallback a Discord / Telegram session uses for ownership — and the session records the speaker for the turn (`Session.caller_person_id`), which `close_open_loop` reads. A DM sent while proactive work is tagged (`attunement.outcomes.tag_proactive` — scheduler dispatch, reflection, research, alert review) also opens an outcome-ledger row at `_record_outbound_context`; a user's own turn is never tagged. Any side-effecting tool call surfaces an `action_taken` chip, which unlike the ephemeral `activity` label is persisted with the assistant message; once the reply is over — also when it was stopped or timed out — the web chat route sends one `sources` event: the documents and web pages the turn looked at (its own search, each specialist that answered, web search results, and the pages the reply cites, which are always kept) and the areas (\"finance\", never a specialist) it had to go without. The web chat shows it under the reply, and it is persisted with the assistant message as `chat_messages.sources`; other channels don't collect it. The stream closes with a `done` event — preceded by a `stopped` event when the user halted the turn, in which case the partial reply is still persisted and flagged so it reads as cut short rather than complete, and is mirrored into the live in-memory session so the next turn's prompt matches what was saved. The stream still ends with `done` event. One side-effecting tool is gated server-side rather than by its description: `ack_alert` will only accept an `alert_id` from the live alert board the server itself derived this turn — the whole live set, not only the rows the `<briefing>` digest printed, since `/today` renders more cards than the digest lists and every one of them is Discuss-able — and it fails closed, so an id it cannot even parse is refused rather than waved through to the handler's own parse. That check runs on **every** session. It used to run only on turns that arrived from a chat channel, keyed on `origin_channel`, which the browser never sets — so the web, the surface the principal actually uses, was unchecked and the model could ack any id, including one quoted out of an alert body by the briefing page's Discuss handoff. What that buys is bounded and worth stating plainly: an id that is invented, closed, snoozed or expired is refused, including one quoted out of an attacker-written alert body; the model being argued into acking the wrong *live* card is not prevented. The one way to widen that set is `find_alerts`, for an item the principal names that has left the live board (already opened, snoozed, older than the board): a keyword search over alerts of every status whose own results — never an id the model supplies — join the trusted set. It runs only in a turn where `render_and_trust` showed the principal their own board (`Session.principal_board_shown`: the verified principal, and on a channel only in their DM), never merely because the session has a set — every `Session` starts with an empty one, and that empty set is how a Google Chat turn, someone else's DM or an unattended pass refuses every ack — and not on the principal's turn in a shared Slack or Discord thread either, where others read the reply and write into what the model reads. It trusts only rows still open (`unread`, `read`), never a roster-request card, and at most 25 ids per turn across calls, and refuses a query with no word of three or more letters. It also moves the admitted limit outward: a model argued into the wrong search can now reach up to 25 open alerts that are off the board, not only live ones. The board is recorded on the turn's `Session`, and the route binds that session for the **whole** SSE body (`schedule_tools.set_session`, alongside `set_turn`) rather than letting `stream_chat` bind it from inside its own generator. `_sse_body` drives the executive with `asyncio.wait_for(stream.__anext__())`, which runs each step in a fresh Task holding a *copy* of the context, so a binding made inside the generator is discarded with the step that made it: step one sees the session and every later step sees `None`. The tool-call loop runs on those later steps, so the whole guard read an empty set and refused every ack on the web — on live, open cards — until the binding moved out to the route. Anything reading `current_session` mid-turn has the same requirement, and two of them needed more than the binding to behave. `schedule_followup`'s seen-`channel_ref` anti-spam gate refuses a send to an address the session has not seen; with no session it skipped itself, so a web turn could schedule to **any** address, and with an empty one it refused even the principal's own. The route now seeds the caller's own addresses onto the session, so on web the gate means what it means on every other surface. Reply linkage (`_record_outbound_context`, read back by `inbound_hydration` to quote the originating conversation into the turn handling a recipient's reply) is the other: it was never reachable on web, and rather than switch that on for the principal's broadest surface as a side effect it is held back, keyed on an explicit `Session.from_web_chat` flag. Not on an empty `origin_channel` — alert review, the CLI and the unattended workflows all leave it empty while legitimately recording linkage, as does the email poller under its own `email` tag. `scheduled_actions` rows also take their `session_id` from the session. A session that was shown no board has an empty trusted set and can ack nothing, so the unattended passes (the nightly reflection, the research synthesis) are refused by default — they also still withhold the tool outright, which is belt-and-braces rather than the only thing stopping them. After the stream closes, the turn is also handed to the episodic memory extractor (`memory.episodic.schedule_extraction`, fire-and-forget) — on every turn where the principal said anything at all, and only the principal: a turn naming an `origin_channel` must resolve to a person marked `is_principal`, because the quote validator downstream cannot tell whose words it is checking. Both this path and the committee path call the same `should_extract` predicate, and it applies no length floor: the gate used to sum in the assistant's reply, which let a verbose answer drag a trivial turn in and discarded the short, decisive instructions that are the whole point of extracting. A user-side floor would fare no better — \"Do B.\" and \"Done\" are one character apart. See **Memory** for what that cost on a live tenant.\n8. **Tool failures** — a handler that raises instead of returning its JSON error is isolated: both tool gathers run with `return_exceptions=True`, the model gets an error `tool_result` naming only the exception's TYPE — a message can carry a filesystem path, a validation error echoing the input, or a third-party HTTP body, and anything in model context can be quoted back to the user, so the full repr stays in the log and the audit row — and the failure is audited with `ok=false`. Only `CancelledError` is re-raised, so turn-timeout and client-disconnect handling still work. Before this one crashing tool aborted the whole turn, which reached the user as an unexplained apology with no audit row (#136).\n\nWeb search, when invoked on the Anthropic path, executes inside the Anthropic API itself (`web_search_20250305`) and returns within the same generation; for any model routed via OpenRouter the same tool becomes OpenRouter's `openrouter:web_search` server tool, which also runs inside the generation with the same search cap and domain lists.\n\nThe install's workspace mode (solo or team, see Org) is read fresh at the start of each turn by `memory.workspace_settings.pin_turn_workspace_mode(session)` and pinned on the session for that turn only (`Session.turn_workspace_mode`): the persona, the org block, the tool list and every tool handler in the turn then agree, and a switch made mid-turn applies from the next turn. A session can instead carry an explicit override, `Session.workspace_mode` (`None` by default), which wins over both — so a caller that runs many conversations concurrently on one Executive, such as evals, can pick the mode per session rather than flipping the install-wide setting. Everything reads it through `effective_workspace_mode(session)` (override, then the turn's pin, then the setting). The principal's role is pinned the same way (`pin_turn_principal_role(session, mode)` → `Session.turn_principal_role`: in solo the `Session.principal_role` override, else the workspace settings read fresh; in team an empty role). The org block renders it, each specialist batch gets it as a `<principal_role>` user-turn tag, and a workflow the turn starts reads the same pin through `effective_principal_role` (override, then the pin, then the setting), so a role edited mid-turn applies from the next turn; a team turn sends none.\n\nAct as me is pinned beside them: `delegation.settings.pin_turn_delegation(session, speaker_text)` records on `Session.turn_delegation` whether the speaker has it on, whether `ghostwrite_email` is offered this turn (the principal, or a team member once the owner lets them, on a verified surface, in a conversation private to them, attended), and the speaker's own words. The pin is also held in a context variable for the turn's task, so two turns running at once on one session each read their own. The tool list, the tool handler and the turn's audit privacy all read that one pin, so a switch flipped mid-turn applies from the next turn. Once the tool touches the speaker's mailbox, the conversation is the speaker's alone (`session_store.mark_mail_private`, the principal included when it isn't theirs), the rest of the turn's audit rows are private (a team member's theirs alone) and the turn teaches no memory: no extraction, open-loop, working-style or Honcho pass runs on it.",
"mermaid": "sequenceDiagram\n participant C as Client\n participant API as FastAPI /chat\n participant E as Executive\n participant CL as Claude\n participant S as Specialists\n participant KB as ChromaDB\n C->>API: POST /chat message\n API->>E: start turn\n E->>CL: messages (tool-use loop)\n CL-->>E: consult_specialist calls\n E->>S: route_parallel fan-out\n S->>KB: domain-filtered RAG\n KB-->>S: chunks\n S-->>E: analysis tool_results\n E->>CL: synthesize\n CL-->>E: streamed reply\n E-->>API: SSE chunks then done\n API-->>C: streamed response",
- "generated_at": "2026-10-01T21:00:00Z"
+ "generated_at": "2026-10-03T16:56:18Z"
}
diff --git a/packages/core/openexecutive/orchestrator/executive.py b/packages/core/openexecutive/orchestrator/executive.py
index e9b69bea..b7cba7a7 100644
--- a/packages/core/openexecutive/orchestrator/executive.py
+++ b/packages/core/openexecutive/orchestrator/executive.py
@@ -140,6 +140,11 @@ from openexecutive.orchestrator.schedule_tools import (
)
from openexecutive.orchestrator.session import Session
from openexecutive.orchestrator.skills_tools import SKILL_TOOL_HANDLERS, SKILL_TOOLS
+from openexecutive.orchestrator.turn_inbox import (
+ TurnInbox,
+ render_added_messages,
+ with_added,
+)
from openexecutive.orchestrator.watchlist_tools import (
WATCHLIST_TOOL_HANDLERS,
WATCHLIST_TOOLS,
@@ -708,6 +713,19 @@ class Executive:
# the direct path; it never earned its slot anyway, since history
# turns are flat strings and the system + tool blocks already
# cover the expensive stable prefix.
+ prev = messages[-1] if messages else None
+ if (
+ prev is not None
+ and prev["role"] == turn["role"]
+ and isinstance(prev["content"], str)
+ and isinstance(turn["content"], str)
+ ):
+ # Two user rows in a row: a message the person sent while
+ # the Executive was working (turn_inbox) is stored as its own
+ # row after the turn's message. One turn per role keeps the
+ # history alternating.
+ prev["content"] = f"{prev['content']}\n\n{turn['content']}"
+ continue
messages.append({"role": turn["role"], "content": turn["content"]})
user_content_parts: list[dict[str, Any]] = []
@@ -827,6 +845,7 @@ class Executive:
memory_text: str | None = None,
turn_sources: TurnSources | None = None,
standing_facts: str | None = None,
+ inbox: TurnInbox | None = None,
) -> AsyncIterator[str | dict[str, Any]]:
"""Stream a response from the Executive, routing to specialists as needed.
@@ -1015,6 +1034,7 @@ class Executive:
turn_sources=turn_sources,
workspace_mode=workspace_mode,
principal_role_tag=principal_role_context(principal_role),
+ inbox=inbox,
):
if isinstance(item, str) and item != self._THINKING:
full_response += item
@@ -1028,6 +1048,8 @@ class Executive:
yield debug_collector.to_sse_dict(evt)
session.add_user_message(user_message)
+ for added_text in inbox.taken_texts() if inbox is not None else []:
+ session.add_user_message(added_text)
session.add_assistant_message(full_response)
# A turn that read or drafted in the speaker's own mailbox (Act as me)
# stays private to them from here on, and teaches no memory: its reply
@@ -1077,7 +1099,7 @@ class Executive:
# has none to learn from: its reply quotes a draft built from other
# people's mail, so should_extract refuses the empty text and every
# other pass below is skipped outright.
- speaker_text = "" if touched_mail else _speaker_text(memory_text, user_message)
+ speaker_text = "" if touched_mail else with_added(_speaker_text(memory_text, user_message), inbox)
# Re-bind the audit ContextVars for the duration of these calls so
# the fire-and-forget tasks they schedule can snapshot the right
@@ -1178,6 +1200,7 @@ class Executive:
memory_text: str | None = None,
turn_sources: TurnSources | None = None,
standing_facts: str | None = None,
+ inbox: TurnInbox | None = None,
) -> AsyncIterator[str | dict[str, Any]]:
"""Committee-reviewed variant of stream_chat.
@@ -1348,6 +1371,7 @@ class Executive:
turn_sources=turn_sources,
workspace_mode=workspace_mode,
principal_role_tag=principal_role_context(principal_role),
+ inbox=inbox,
):
# Swallow draft text and the THINKING sentinel — the user sees
# only the revised stream. Pass debug-event dicts through so the
@@ -1384,6 +1408,8 @@ class Executive:
fallback = "I was unable to complete the analysis. Please try again."
yield fallback
session.add_user_message(user_message)
+ for added_text in inbox.taken_texts() if inbox is not None else []:
+ session.add_user_message(added_text)
session.add_assistant_message(fallback)
# Reset audit ContextVars so this task doesn't leak the turn_id
# to a follow-up turn that runs on the same task.
@@ -1525,6 +1551,8 @@ class Executive:
yield debug_collector.to_sse_dict(evt)
session.add_user_message(user_message)
+ for added_text in inbox.taken_texts() if inbox is not None else []:
+ session.add_user_message(added_text)
# Act as me: a turn that touched the speaker's mailbox stays private
# and teaches no memory (see stream_chat).
touched_mail = delegation_pin.touched_mail
@@ -1590,7 +1618,7 @@ class Executive:
# The speaker's own words, for extraction, open loops and peer
# memory alike — none for a turn that touched their mailbox; see
# stream_chat.
- speaker_text = "" if touched_mail else _speaker_text(memory_text, user_message)
+ speaker_text = "" if touched_mail else with_added(_speaker_text(memory_text, user_message), inbox)
# private_rows: see stream_chat — the scheduled passes copy it.
with private_rows(touched_mail):
if should_extract(speaker_text, session=session):
@@ -1659,6 +1687,7 @@ class Executive:
turn_sources: TurnSources | None = None,
workspace_mode: str | None = None,
principal_role_tag: str | None = None,
+ inbox: TurnInbox | None = None,
) -> AsyncIterator[str | dict[str, Any]]:
"""Tool-use loop that yields text deltas as they arrive.
@@ -1677,6 +1706,10 @@ class Executive:
``principal_role_tag`` is the specialists' ``<principal_role>`` body
for the turn, resolved by the caller with the mode ("" for none);
None resolves it here from the current session — solo only.
+
+ ``inbox`` holds messages the person sent while this turn runs (the
+ web chat's POST /chat/add). Whatever has arrived is added after each
+ round's tool results, and a ``message_added`` event names it.
"""
if workspace_mode is None:
workspace_mode = effective_workspace_mode(current_session.get())
@@ -2386,6 +2419,16 @@ class Executive:
}
for tu in tool_uses
]
+ # Messages the person sent since the last round ride in this
+ # round's user message, after the tool results (which must come
+ # first). Only this loop's own, newest message changes, so the
+ # cached prefix is untouched.
+ added = inbox.take() if inbox is not None else []
+ if added:
+ tool_results.append({"type": "text", "text": render_added_messages(added)})
+ # Audited by the inbox's owner (the web chat route), under
+ # the same privacy as the turn's own message.
+ yield {"type": "message_added", "ids": [m.id for m in added]}
current_messages.append({"role": "user", "content": tool_results})
# Bounded to the messages this loop appended: current_messages
# is a shallow copy, so anything at a lower index is still owned
diff --git a/packages/core/openexecutive/orchestrator/turn_inbox.py b/packages/core/openexecutive/orchestrator/turn_inbox.py
new file mode 100644
index 00000000..1f9e9682
--- /dev/null
+++ b/packages/core/openexecutive/orchestrator/turn_inbox.py
@@ -0,0 +1,93 @@
+"""Messages a person sends while the Executive is still working on a turn.
+
+The web chat keeps its box open during a turn. A message typed then is handed
+to the running turn's inbox (POST /chat/add) instead of starting a second
+turn. The agent loop takes whatever has arrived at each step boundary (after a
+round of tool results, before the next model call) and adds it to that round's
+user message, so the answer it is writing takes the new message into account.
+
+A message that arrives after the last step boundary (while the final answer is
+being written) is never taken. The turn closes its inbox when it ends, and the
+client sends anything not taken as the next turn, so nothing is lost and
+nothing is answered twice.
+
+Single-process, like the stop registry in ``api/routes/chat.py`` that owns
+each inbox.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# Bounds on what one turn will hold. A person adding a line or two is the use;
+# these only stop a runaway client from growing the prompt without limit.
+MAX_PENDING_MESSAGES = 10
+MAX_MESSAGE_CHARS = 32000
+
+
+@dataclass
+class AddedMessage:
+ # Client-minted, so the client can tell which of its queued bubbles the
+ # turn took (the `message_added` event names them).
+ id: str
+ text: str
+
+
+@dataclass
+class TurnInbox:
+ _pending: list[AddedMessage] = field(default_factory=list)
+ # Everything the turn took, in arrival order: persisted after the turn's
+ # own message and mirrored into the session history.
+ taken: list[AddedMessage] = field(default_factory=list)
+ closed: bool = False
+
+ def add(self, message_id: str, text: str) -> bool:
+ """Queue a message for the running turn. False once the turn has
+ closed its inbox, for a duplicate id, or when the inbox is full; the
+ client then sends the message as the next turn instead."""
+ if self.closed or not text.strip() or len(text) > MAX_MESSAGE_CHARS:
+ return False
+ if len(self._pending) + len(self.taken) >= MAX_PENDING_MESSAGES:
+ return False
+ if any(m.id == message_id for m in (*self._pending, *self.taken)):
+ return False
+ self._pending.append(AddedMessage(message_id, text))
+ return True
+
+ def take(self) -> list[AddedMessage]:
+ """Hand the loop everything that arrived since the last take."""
+ if self.closed or not self._pending:
+ return []
+ out, self._pending = self._pending, []
+ self.taken.extend(out)
+ return out
+
+ def close(self) -> None:
+ """Refuse further messages. Anything still pending was never seen by
+ the model; the client resends it as the next turn."""
+ self.closed = True
+ self._pending = []
+
+ def taken_texts(self) -> list[str]:
+ return [m.text for m in self.taken]
+
+
+def render_added_messages(added: list[AddedMessage]) -> str:
+ """The text block the loop adds after a round's tool results."""
+ lines = [
+ "While you were working on this, they sent another message. It is "
+ "from the same person as their message above. Take it into account "
+ "in this answer: if it changes or corrects what they asked, follow "
+ "the newer message.",
+ ]
+ for m in added:
+ lines.append(f"<added_message>\n{m.text}\n</added_message>")
+ return "\n\n".join(lines)
+
+
+def with_added(text: str, inbox: TurnInbox | None) -> str:
+ """``text`` followed by the messages the turn took, for the passes that
+ read the person's own words for the turn (memory, open loops)."""
+ if inbox is None or not inbox.taken:
+ return text
+ return "\n\n".join([text, *inbox.taken_texts()]) if text else text
diff --git a/packages/core/tests/unit/test_chat_route_added_messages.py b/packages/core/tests/unit/test_chat_route_added_messages.py
new file mode 100644
index 00000000..33d3e450
--- /dev/null
+++ b/packages/core/tests/unit/test_chat_route_added_messages.py
@@ -0,0 +1,147 @@
+"""A message added mid-turn (POST /chat/add) is saved with the turn it joined.
+
+Same harness as test_chat_route_stop.py: TestClient buffers the whole SSE
+response, so the fake Executive delivers the message from inside its own
+generator, through the same registry the endpoint uses.
+"""
+from __future__ import annotations
+
+import json
+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.memory import episodic, session_store
+from openexecutive.memory.company_profile import CompanyProfile
+
+CLIENT_ID = "add-to-me-0000-01"
+
+
+def _events(body: str) -> list[dict[str, Any]]:
+ return [json.loads(line[6:]) for line in body.splitlines() if line.startswith("data: ")]
+
+
[email protected](autouse=True)
+def _reset_route_state() -> None:
+ chat_route._sessions.clear()
+ chat_route._active_stops.clear()
+ chat_route._session_turn_locks.clear()
+
+
+def temp_db(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ monkeypatch.chdir(tmp_path)
+ db_path = Path("./episodic_memory.db").resolve()
+ monkeypatch.setattr(episodic, "DB_PATH", db_path)
+ monkeypatch.setattr(session_store, "DB_PATH", db_path)
+ episodic.initialize_db(db_path)
+ return db_path
+
+
[email protected](autouse=True)
+def patched_deps(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+ from openexecutive import audit
+ from openexecutive.knowledge import retriever
+ from openexecutive.onboarding import profile_builder
+ from openexecutive.utils import session_title as _title_mod
+
+ monkeypatch.setattr(profile_builder, "load_or_create_profile", lambda: CompanyProfile())
+ monkeypatch.setattr(retriever, "retrieve", lambda query, specialist_name=None, store=None, **_k: "")
+
+ async def _no_title(*_a: Any, **_k: Any) -> None:
+ return None
+
+ monkeypatch.setattr(_title_mod, "generate_session_title", _no_title)
+ monkeypatch.setattr(audit, "log_event", lambda *a, **k: None)
+ monkeypatch.setattr(chat_route, "audit_log", lambda *a, **k: _audited.append((a, k)))
+
+
+_audited: list[tuple[Any, Any]] = []
+
+
+def _fake_executive(monkeypatch: pytest.MonkeyPatch, *, late: bool = False) -> None:
+ """A turn that is sent "make it Friday" while it works. With ``late`` the
+ message arrives after the turn's last step, so it is never taken."""
+ from openexecutive.orchestrator import executive as exec_mod
+
+ class _Exec:
+ _THINKING = exec_mod.Executive._THINKING
+
+ def __init__(self, **_kwargs: Any) -> None:
+ pass
+
+ async def stream_chat(self, *, inbox: Any = None, session: Any, user_message: str, **_k: Any) -> Any:
+ assert inbox is not None
+ assert chat_route._add_to_turn(CLIENT_ID, "local", "msg-000001", "make it Friday")
+ if not late:
+ taken = inbox.take()
+ yield {"type": "message_added", "ids": [m.id for m in taken]}
+ yield "Booked for Friday."
+ session.add_user_message(user_message)
+ for t in inbox.taken_texts():
+ session.add_user_message(t)
+ session.add_assistant_message("Booked for Friday.")
+
+ monkeypatch.setattr(exec_mod, "Executive", _Exec)
+
+
+def _client() -> TestClient:
+ app = FastAPI()
+ app.include_router(chat_route.router)
+ return TestClient(app)
+
+
+def test_added_message_is_saved_between_the_turn_and_its_reply(
+ temp_db: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _fake_executive(monkeypatch)
+ resp = _client().post("/chat", json={"message": "book the room", "client_turn_id": CLIENT_ID})
+
+ events = _events(resp.text)
+ assert {"type": "message_added", "ids": ["msg-000001"]} in events
+ session_id = events[-1]["session_id"]
+ saved = session_store.load_messages(session_id)
+ assert [(m["role"], m["content"]) for m in saved] == [
+ ("user", "book the room"),
+ ("user", "make it Friday"),
+ ("assistant", "Booked for Friday."),
+ ]
+ # Audited as the person's words, like the turn's own message.
+ assert any("added while working" in a[1] and k["actor"] == "user" for a, k in _audited)
+ # Closed with the turn: nothing more can join it.
+ assert chat_route._active_stops == {}
+ assert chat_route._add_to_turn(CLIENT_ID, "local", "msg-000002", "x") is None
+
+
+def test_message_the_turn_never_took_is_not_saved(
+ temp_db: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _fake_executive(monkeypatch, late=True)
+ resp = _client().post("/chat", json={"message": "book the room", "client_turn_id": CLIENT_ID})
+
+ events = _events(resp.text)
+ assert not any(e.get("type") == "message_added" for e in events)
+ saved = session_store.load_messages(events[-1]["session_id"])
+ # The client sends it as the next turn instead.
+ assert [m["content"] for m in saved] == ["book the room", "Booked for Friday."]
+
+
+def test_continuing_a_conversation_releases_its_turn_lock(
+ temp_db: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _fake_executive(monkeypatch)
+ first = _client().post("/chat", json={"message": "book the room", "client_turn_id": CLIENT_ID})
+ session_id = _events(first.text)[-1]["session_id"]
+
+ second = _client().post(
+ "/chat",
+ json={"message": "and lunch", "session_id": session_id, "client_turn_id": CLIENT_ID},
+ )
+ assert second.status_code == 200
+ assert _events(second.text)[-1]["type"] == "done"
+ assert chat_route._session_turn_locks == {}
diff --git a/packages/core/tests/unit/test_turn_inbox.py b/packages/core/tests/unit/test_turn_inbox.py
new file mode 100644
index 00000000..d5639295
--- /dev/null
+++ b/packages/core/tests/unit/test_turn_inbox.py
@@ -0,0 +1,329 @@
+"""Messages sent while the Executive works are folded into the running turn.
+
+Covers the inbox itself (orchestrator/turn_inbox.py), the agent loop taking
+it at a step boundary, the history merge that keeps stored rows alternating,
+POST /chat/add, and the one-turn-at-a-time lock on a web conversation.
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from openexecutive.api.routes import chat as chat_route
+from openexecutive.orchestrator.executive import Executive
+from openexecutive.orchestrator.session import Session
+from openexecutive.orchestrator.turn_inbox import (
+ MAX_PENDING_MESSAGES,
+ TurnInbox,
+ render_added_messages,
+ with_added,
+)
+
+from ._agent_loop_fakes import FakeStream, FinalMsg, ScriptedProvider, TextBlock, ToolUseBlock
+
+# ---------------------------------------------------------------- inbox --
+
+
+def test_take_hands_over_pending_once_in_order() -> None:
+ inbox = TurnInbox()
+ assert inbox.add("m-000001", "make it Friday")
+ assert inbox.add("m-000002", "and cc Dana")
+ taken = inbox.take()
+ assert [m.text for m in taken] == ["make it Friday", "and cc Dana"]
+ assert inbox.take() == []
+ assert inbox.taken_texts() == ["make it Friday", "and cc Dana"]
+
+
+def test_closed_inbox_refuses_and_drops_what_was_never_taken() -> None:
+ inbox = TurnInbox()
+ inbox.add("m-000001", "first")
+ inbox.take()
+ inbox.add("m-000002", "too late")
+ inbox.close()
+ assert not inbox.add("m-000003", "after close")
+ assert inbox.take() == []
+ # Only what the model saw counts as part of the turn.
+ assert inbox.taken_texts() == ["first"]
+
+
+def test_duplicate_blank_and_overflow_are_refused() -> None:
+ inbox = TurnInbox()
+ assert inbox.add("m-000001", "one")
+ assert not inbox.add("m-000001", "same id again")
+ assert not inbox.add("m-000002", " ")
+ for i in range(2, MAX_PENDING_MESSAGES + 1):
+ assert inbox.add(f"m-{i:06d}", f"msg {i}")
+ assert not inbox.add("m-999999", "one too many")
+
+
+def test_with_added_appends_taken_words_only() -> None:
+ inbox = TurnInbox()
+ inbox.add("m-000001", "make it Friday")
+ assert with_added("book the room", inbox) == "book the room"
+ inbox.take()
+ assert with_added("book the room", inbox) == "book the room\n\nmake it Friday"
+ # A turn with nothing to learn from (Act as me) stays empty.
+ assert with_added("", inbox) == ""
+ assert with_added("x", None) == "x"
+
+
+# ----------------------------------------------------------- agent loop --
+
+
+class _StubGateway:
+ async def call_tool(self, _input: dict[str, Any]) -> str:
+ return '{"status": "ok"}'
+
+ async def search_tools(self, _input: dict[str, Any]) -> str:
+ return '{"tools": []}'
+
+ async def load_mcp_server(self, _input: dict[str, Any]) -> str:
+ return '{"status": "ok"}'
+
+
+class _ArrivingProvider(ScriptedProvider):
+ """Delivers a message into the inbox while each model call runs."""
+
+ def __init__(self, final_msgs: list[FinalMsg], inbox: TurnInbox, arrivals: list[str]) -> None:
+ super().__init__(final_msgs)
+ self._inbox = inbox
+ self._arrivals = list(arrivals)
+
+ def messages_stream(self, **kwargs: Any) -> FakeStream:
+ if self._arrivals:
+ n = len(self.calls) + 1
+ self._inbox.add(f"msg-{n:06d}", self._arrivals.pop(0))
+ return super().messages_stream(**kwargs)
+
+
[email protected](autouse=True)
+def _no_audit(monkeypatch: pytest.MonkeyPatch) -> list[tuple[Any, ...]]:
+ rows: list[tuple[Any, ...]] = []
+ monkeypatch.setattr(
+ "openexecutive.orchestrator.executive.audit_log",
+ lambda *a, **k: rows.append((a, k)),
+ )
+ return rows
+
+
+def _run(provider: ScriptedProvider, inbox: TurnInbox) -> list[Any]:
+ executive = Executive()
+ executive._mcp_gateway = _StubGateway() # type: ignore[assignment]
+
+ async def _go() -> list[Any]:
+ items: list[Any] = []
+ with patch("openexecutive.orchestrator.executive.get_provider", return_value=provider):
+ async for item in executive._stream_agent_loop(
+ system_blocks=[],
+ messages=[{"role": "user", "content": "book the room"}],
+ model="claude-test",
+ inbox=inbox,
+ ):
+ items.append(item)
+ return items
+
+ return asyncio.run(_go())
+
+
+def _tool_round() -> FinalMsg:
+ return FinalMsg(
+ [ToolUseBlock("toolu_1", "call_tool", {"name": "calendar__find_room", "arguments": {}})],
+ "tool_use",
+ )
+
+
+def test_message_sent_during_a_tool_round_reaches_the_next_call() -> None:
+ inbox = TurnInbox()
+ provider = _ArrivingProvider(
+ [_tool_round(), FinalMsg([TextBlock("Booked for Friday.")], "end_turn")],
+ inbox,
+ ["actually make it Friday"],
+ )
+ items = _run(provider, inbox)
+
+ last_user = provider.calls[1]["messages"][-1]
+ assert last_user["role"] == "user"
+ blocks = last_user["content"]
+ # Tool results first (the API requires it), then the added message.
+ assert blocks[0]["type"] == "tool_result"
+ assert blocks[-1]["type"] == "text"
+ assert "actually make it Friday" in blocks[-1]["text"]
+ assert {"type": "message_added", "ids": ["msg-000001"]} in items
+ assert inbox.taken_texts() == ["actually make it Friday"]
+
+
+def test_message_sent_during_the_final_answer_is_left_for_the_next_turn() -> None:
+ inbox = TurnInbox()
+ provider = _ArrivingProvider(
+ [_tool_round(), FinalMsg([TextBlock("Booked.")], "end_turn")],
+ inbox,
+ ["first", "while it writes the answer"],
+ )
+ items = _run(provider, inbox)
+ inbox.close()
+
+ added = [i for i in items if isinstance(i, dict) and i.get("type") == "message_added"]
+ assert added == [{"type": "message_added", "ids": ["msg-000001"]}]
+ assert inbox.taken_texts() == ["first"]
+
+
+def test_render_names_the_newer_message_as_winning() -> None:
+ inbox = TurnInbox()
+ inbox.add("m-000001", "make it Friday")
+ text = render_added_messages(inbox.take())
+ assert "<added_message>\nmake it Friday\n</added_message>" in text
+ assert "follow the newer message" in text
+
+
+def test_history_with_two_user_rows_is_sent_as_one_user_turn() -> None:
+ session = Session(session_id="s-merge")
+ session.conversation_history = [
+ {"role": "user", "content": "book the room"},
+ {"role": "user", "content": "make it Friday"},
+ {"role": "assistant", "content": "Booked for Friday."},
+ ]
+ messages = Executive()._build_messages(session, "thanks")
+ assert messages[0] == {"role": "user", "content": "book the room\n\nmake it Friday"}
+ assert messages[1]["role"] == "assistant"
+ assert [m["role"] for m in messages] == ["user", "assistant", "user"]
+ # The session's own rows are untouched.
+ assert session.conversation_history[0]["content"] == "book the room"
+
+
+# ------------------------------------------------------------ /chat/add --
+
+
+def client(monkeypatch: pytest.MonkeyPatch) -> TestClient:
+ chat_route._active_stops.clear()
+ monkeypatch.setattr(chat_route, "_resolve_caller_person_id", lambda _r: 7)
+ app = FastAPI()
+ app.include_router(chat_route.router)
+ yield TestClient(app)
+ chat_route._active_stops.clear()
+
+
+def _seed(client_turn_id: str, owner: str) -> chat_route._StopEntry:
+ entry = chat_route._StopEntry(
+ asyncio.Event(), owner, "t-abc123456789", time.monotonic(), TurnInbox()
+ )
+ chat_route._active_stops[client_turn_id] = entry
+ return entry
+
+
+def _add(client: TestClient, turn: str, msg_id: str = "msg-000001", text: str = "make it Friday") -> Any:
+ return client.post(
+ "/chat/add", json={"client_turn_id": turn, "message_id": msg_id, "message": text}
+ )
+
+
+def test_add_queues_for_the_owner(client: TestClient) -> None:
+ entry = _seed("live-turn-0001", "person:7")
+ resp = _add(client, "live-turn-0001")
+ assert resp.status_code == 200
+ assert resp.json() == {"status": "added", "turn_id": "t-abc123456789"}
+ assert entry.inbox is not None
+ assert [m.text for m in entry.inbox.take()] == ["make it Friday"]
+
+
+def test_add_to_someone_elses_or_unknown_turn_is_the_same_404(client: TestClient) -> None:
+ entry = _seed("someone-elses-1", "person:99")
+ theirs = _add(client, "someone-elses-1")
+ unknown = _add(client, "no-such-turn-1")
+ assert theirs.status_code == unknown.status_code == 404
+ assert theirs.json() == unknown.json()
+ assert entry.inbox is not None and entry.inbox.take() == []
+
+
+def test_add_to_a_stopped_or_closed_turn_is_404(client: TestClient) -> None:
+ stopped = _seed("stopped-turn-1", "person:7")
+ stopped.event.set()
+ assert _add(client, "stopped-turn-1").status_code == 404
+ closed = _seed("closed-turn-01", "person:7")
+ assert closed.inbox is not None
+ closed.inbox.close()
+ assert _add(client, "closed-turn-01").status_code == 404
+
+
+def test_add_rejects_a_malformed_message_id(client: TestClient) -> None:
+ _seed("live-turn-0002", "person:7")
+ assert _add(client, "live-turn-0002", msg_id="bad id\n").status_code == 422
+
+
+def test_registered_turns_get_an_inbox() -> None:
+ chat_route._active_stops.clear()
+ try:
+ assert chat_route._register_stop("new-turn-00001", "person:7", "t-new00000000")
+ assert isinstance(chat_route._active_stops["new-turn-00001"].inbox, TurnInbox)
+ finally:
+ chat_route._active_stops.clear()
+
+
+# ------------------------------------------------------- session lock --
+
+
+def test_second_turn_on_a_conversation_waits_for_the_first() -> None:
+ async def _go() -> list[str]:
+ order: list[str] = []
+ first = await chat_route._acquire_session_turn("conv-1", 5)
+ assert first is not None
+
+ async def second() -> None:
+ lock = await chat_route._acquire_session_turn("conv-1", 5)
+ order.append("second")
+ chat_route._release_session_turn("conv-1", lock)
+
+ task = asyncio.create_task(second())
+ await asyncio.sleep(0.01)
+ order.append("first done")
+ chat_route._release_session_turn("conv-1", first)
+ await task
+ return order
+
+ assert asyncio.run(_go()) == ["first done", "second"]
+ assert "conv-1" not in chat_route._session_turn_locks
+
+
+def test_a_turn_arriving_as_the_lock_passes_on_still_waits() -> None:
+ """A releases with B queued; C arrives before B has run. C must queue on
+ the same lock, not find the map empty and run beside B."""
+
+ async def _go() -> list[str]:
+ events: list[str] = []
+ a = await chat_route._acquire_session_turn("conv-3", 5)
+
+ async def turn(name: str) -> None:
+ lock = await chat_route._acquire_session_turn("conv-3", 5)
+ events.append(f"{name} start")
+ await asyncio.sleep(0.01)
+ events.append(f"{name} end")
+ chat_route._release_session_turn("conv-3", lock)
+
+ b = asyncio.create_task(turn("B"))
+ await asyncio.sleep(0)
+ chat_route._release_session_turn("conv-3", a)
+ c = asyncio.create_task(turn("C"))
+ await asyncio.gather(b, c)
+ return events
+
+ assert asyncio.run(_go()) == ["B start", "B end", "C start", "C end"]
+ assert "conv-3" not in chat_route._session_turn_locks
+ assert "conv-3" not in chat_route._session_turn_users
+
+
+def test_lock_wait_is_bounded() -> None:
+ async def _go() -> Any:
+ held = await chat_route._acquire_session_turn("conv-2", 5)
+ late = await chat_route._acquire_session_turn("conv-2", 0.01)
+ chat_route._release_session_turn("conv-2", held)
+ return late
+
+ assert asyncio.run(_go()) is None
+ assert "conv-2" not in chat_route._session_turn_locks
+ assert "conv-2" not in chat_route._session_turn_users
diff --git a/packages/ui/scripts/queuedMessages.test.mjs b/packages/ui/scripts/queuedMessages.test.mjs
new file mode 100644
index 00000000..a5d213d1
--- /dev/null
+++ b/packages/ui/scripts/queuedMessages.test.mjs
@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { composerText, markTaken, settleQueue } from "../src/lib/queuedMessages.ts";
+
+const q = [
+ { id: "a", text: "make it Friday", taken: false },
+ { id: "b", text: "and cc Dana", taken: false },
+];
+
+test("markTaken flags only the named messages", () => {
+ const out = markTaken(q, ["b"]);
+ assert.deepEqual(out.map((m) => m.taken), [false, true]);
+ assert.equal(markTaken(q, []), q);
+});
+
+test("taken messages stay with the reply, the rest become the next turn", () => {
+ const settled = settleQueue(markTaken(q, ["a"]));
+ assert.deepEqual(settled.taken, ["make it Friday"]);
+ assert.equal(settled.next, "and cc Dana");
+});
+
+test("nothing left means no next turn", () => {
+ assert.equal(settleQueue(markTaken(q, ["a", "b"])).next, null);
+ assert.deepEqual(settleQueue([]), { taken: [], next: null });
+});
+
+test("several leftovers are sent as one message, in order", () => {
+ assert.equal(settleQueue(q).next, "make it Friday\n\nand cc Dana");
+});
+
+test("composerText returns everything to the composer, skipping blanks", () => {
+ assert.equal(composerText("book the room", q), "book the room\n\nmake it Friday\n\nand cc Dana");
+ assert.equal(composerText("", q), "make it Friday\n\nand cc Dana");
+});
diff --git a/packages/ui/src/components/Chat.tsx b/packages/ui/src/components/Chat.tsx
index 6fc2cf4a..cc1b334a 100644
--- a/packages/ui/src/components/Chat.tsx
+++ b/packages/ui/src/components/Chat.tsx
@@ -14,6 +14,7 @@ import {
} from "@/lib/file-attachments";
import {
ActionTaken,
+ addChatMessage,
ChatMessage,
CommitteePhase,
DebugEvent,
@@ -25,6 +26,13 @@ import {
} from "@/lib/api";
import { answerSourcesFrom, type AnswerSources } from "@/lib/answerSources";
import { isAbortError, useStoppableTurn } from "@/lib/use-stoppable-turn";
+import {
+ composerText,
+ markTaken,
+ settleQueue,
+ type QueuedMessage,
+} from "@/lib/queuedMessages";
+import { newClientTurnId } from "@/lib/turn-id";
import { turnStatus } from "@/lib/turnStatus";
interface ChatProps {
@@ -62,6 +70,7 @@ const SUGGESTED_PROMPTS = [
];
const DEFAULT_PLACEHOLDER = "What's on your mind?";
+const WORKING_PLACEHOLDER = "Add something while it works…";
// A follow-up is only worth suggesting when the conversation ends on a
// persisted reply — the backend keys its suggestion on that reply's id.
@@ -105,6 +114,16 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
const textareaRef = useRef<HTMLTextAreaElement>(null);
const fileInputRef = useRef<HTMLInputElement>(null);
const adoptedSessionIdRef = useRef<string | undefined>(initialSessionId);
+ // Messages typed while a turn runs (see lib/queuedMessages). The ref is
+ // what the turn reads when it ends; the state is what renders.
+ const [queued, setQueuedState] = useState<QueuedMessage[]>([]);
+ const queuedRef = useRef<QueuedMessage[]>([]);
+ function setQueued(next: QueuedMessage[]) {
+ queuedRef.current = next;
+ setQueuedState(next);
+ }
+ // The running turn's id, which addresses it for POST /chat/add.
+ const turnIdRef = useRef<string | null>(null);
useEffect(() => {
const ctrl = new AbortController();
@@ -176,15 +195,15 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
// We pass the prompt explicitly into handleSend so the state-clearing in
// handleSend doesn't race with React batching `setInput("")` after the
// submit reads it back.
- // Escape stops the turn. This has to be a document listener rather than the
- // textarea's onKeyDown: the textarea is `disabled` while a turn is in
- // flight, and a disabled element cannot hold focus or emit key events — so
- // the one condition under which we want Escape is exactly the one where the
- // textarea handler can never run.
+ // Escape stops the turn, wherever focus is: a document listener rather than
+ // the textarea's onKeyDown, so it works with focus on the page too. Not
+ // while something is being typed to add to the turn, where Escape throwing
+ // away the answer would be a nasty surprise.
useEffect(() => {
if (!isLoading) return;
const onKey = (e: KeyboardEvent) => {
if (e.key !== "Escape") return;
+ if (textareaRef.current?.value.trim()) return;
// An overlay that consumed this Escape (a tooltip, a dialog) calls
// preventDefault. Stopping the turn as well would make one keypress do
// two unrelated things.
@@ -222,7 +241,27 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
setSessionId(id);
}
- async function handleSend(text?: string, memoryText?: string) {
+ // A message typed while the Executive works goes to the running turn, which
+ // folds it into the answer it is writing. If the turn can't take it any
+ // more, it is sent as the next turn when this one ends.
+ function addWhileWorking() {
+ const text = input.trim();
+ const turnId = turnIdRef.current;
+ if (!text || !turnId) return;
+ const id = newClientTurnId();
+ setInput("");
+ if (textareaRef.current) textareaRef.current.style.height = "auto";
+ setQueued([...queuedRef.current, { id, text, taken: false }]);
+ void addChatMessage(turnId, id, text);
+ }
+
+ // `queuedFollowup`: the leftovers of a turn, sent on their own. They carry
+ // no files and leave alone whatever is being typed in the composer now.
+ async function handleSend(text?: string, memoryText?: string, queuedFollowup = false) {
+ if (isLoading && text === undefined) {
+ addWhileWorking();
+ return;
+ }
const message = (text ?? input).trim();
if ((!message && pendingFiles.length === 0) || isLoading) return;
const restored = restoredHandoffRef.current;
@@ -231,14 +270,16 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
memoryText ??
(text === undefined && restored?.seed === message ? restored.memoryText : undefined);
- const filesForTurn = pendingFiles;
+ const filesForTurn = queuedFollowup ? [] : pendingFiles;
const userBubbleContent = filesForTurn.length
? `${message}${message ? "\n\n" : ""}📎 ${filesForTurn.length} file${filesForTurn.length === 1 ? "" : "s"} attached`
: message;
- setInput("");
- setPendingFiles([]);
- setFileError(null);
+ if (!queuedFollowup) {
+ setInput("");
+ setPendingFiles([]);
+ setFileError(null);
+ }
clearFollowup();
setMessages((prev) => [...prev, { role: "user", content: userBubbleContent }]);
setIsLoading(true);
@@ -249,9 +290,11 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
setActivityLabel(null);
setCommitteePhase(null);
const { clientTurnId, signal } = beginTurn();
+ turnIdRef.current = clientTurnId;
+ setQueued([]);
onTurnStart?.();
- if (textareaRef.current) {
+ if (textareaRef.current && !queuedFollowup) {
textareaRef.current.style.height = "auto";
}
@@ -269,9 +312,22 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
let replyId: number | undefined;
// Session id from `done`, used to fetch the follow-up for this reply.
let doneSessionId: string | undefined;
+ // What the queue left to send as the next turn, once this one settles.
+ let nextTurn: string | null = null;
+ // Messages the turn took, shown before its reply. Each settle path that
+ // keeps the reply also keeps these.
+ const settleWithReply = () => {
+ const settled = settleQueue(queuedRef.current);
+ setQueued([]);
+ nextTurn = settled.next;
+ return settled.taken.map((t): ChatMessage => ({ role: "user", content: t }));
+ };
try {
- for await (const item of streamChat(message, sessionId, {
+ // The ref, not the state: a turn sent straight after the previous one
+ // (a message queued while it worked) runs before the state catches up,
+ // and must still continue the conversation it was typed in.
+ for await (const item of streamChat(message, adoptedSessionIdRef.current, {
committeeReview: committeeEnabled,
files: filesForTurn,
clientTurnId,
@@ -310,6 +366,8 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
setStreamingActions([...turnActions]);
} else if (item.type === "sources") {
turnSources = answerSourcesFrom(item);
+ } else if (item.type === "message_added") {
+ setQueued(markTaken(queuedRef.current, item.ids));
} else if (item.type === "stopped") {
// The server acknowledged the stop and is winding the turn down
// itself; `done` follows over the same stream. Stand the abort
@@ -338,20 +396,27 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
// and can edit and resend. Skipped when files were attached — dropping a
// file selection without saying so would be worse than the mismatch.
if (wasStopped && !accumulated && turnActions.length === 0) {
+ // Nothing was saved, so nothing typed while it worked was either.
+ const extra = queuedRef.current;
+ setQueued([]);
if (filesForTurn.length === 0) {
setMessages((prev) =>
prev.length && prev[prev.length - 1].role === "user"
? prev.slice(0, -1)
: prev,
);
- setInput(message);
- restoredHandoffRef.current = turnMemoryText
+ setInput(composerText(message, extra));
+ restoredHandoffRef.current = turnMemoryText && extra.length === 0
? { seed: message, memoryText: turnMemoryText }
: undefined;
+ } else if (extra.length > 0) {
+ setInput(composerText("", extra));
}
} else if (accumulated || turnActions.length > 0) {
+ const takenBubbles = settleWithReply();
setMessages((prev) => [
...prev,
+ ...takenBubbles,
{
role: "assistant",
content: accumulated,
@@ -372,8 +437,10 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
// Our own safety-net abort fired (the server never sent `stopped`).
// Keep whatever streamed; this is a stop, not a failure.
if (accumulated || turnActions.length > 0) {
+ const takenBubbles = settleWithReply();
setMessages((prev) => [
...prev,
+ ...takenBubbles,
{
role: "assistant",
content: accumulated,
@@ -382,6 +449,9 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
sources: turnSources,
},
]);
+ } else if (queuedRef.current.length > 0) {
+ setInput(composerText("", queuedRef.current));
+ setQueued([]);
}
// `done` never arrived, so nothing else will clear the parent's
// in-flight state or refresh the sidebar. Safe to call with an empty
@@ -389,6 +459,12 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
onTurnComplete?.(adoptedSessionIdRef.current ?? sessionId ?? "");
} else {
const detail = err instanceof Error ? err.message : String(err);
+ // A failed turn saved nothing: give back what was typed while it
+ // worked rather than sending it into the same failure.
+ if (queuedRef.current.length > 0) {
+ setInput(composerText("", queuedRef.current));
+ setQueued([]);
+ }
setMessages((prev) => [
...prev,
{ role: "assistant", content: `Something went wrong: ${detail}` },
@@ -398,12 +474,16 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
setStreamingActions([]);
} finally {
endTurn();
+ turnIdRef.current = null;
setIsLoading(false);
setIsConsulting(false);
setActivityLabel(null);
setCommitteePhase(null);
textareaRef.current?.focus();
}
+ // What was typed while it worked and the turn never got to: its own turn
+ // now, in the same conversation.
+ if (nextTurn) void handleSend(nextTurn, undefined, true);
}
// 👍/👎 on a persisted reply, applied optimistically and rolled back if
@@ -559,6 +639,17 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
/>
))}
+ {queued.map((q) => (
+ <div key={q.id} className="flex flex-col items-end mb-6">
+ <div className="max-w-xl px-4 py-3 rounded-2xl rounded-tr-sm bg-surface-overlay text-fg text-sm leading-relaxed">
+ <p className="whitespace-pre-wrap">{q.text}</p>
+ </div>
+ <p className="mt-1 text-xs text-fg-muted" aria-live="polite">
+ {q.taken ? "👀 Seen, taking it into this answer" : "Sent while it works"}
+ </p>
+ </div>
+ ))}
+
{streamingContent && (
<Message
role="assistant"
@@ -689,9 +780,8 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
value={input}
onChange={handleTextareaChange}
onKeyDown={handleKeyDown}
- placeholder={followup ?? DEFAULT_PLACEHOLDER}
+ placeholder={isLoading ? WORKING_PLACEHOLDER : followup ?? DEFAULT_PLACEHOLDER}
rows={1}
- disabled={isLoading}
aria-label="Message"
className={
"col-start-1 row-start-1 w-full bg-transparent text-fg text-sm sm:text-base leading-relaxed resize-none focus:outline-none disabled:opacity-50 max-h-40 overflow-y-auto " +
@@ -700,7 +790,7 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
style={{ minHeight: "24px" }}
/>
</div>
- {isLoading ? (
+ {isLoading && (
<button
type="button"
onClick={handleStop}
@@ -711,12 +801,14 @@ export default function Chat({ onDebugEvent, initialMessages, initialSessionId,
>
<Icon name="stop" size="w-3.5 h-3.5" fill="currentColor" />
</button>
- ) : (
+ )}
+ {/* While it works, Send appears once there is something to add. */}
+ {(!isLoading || input.trim()) && (
<button
type="button"
onClick={() => handleSend()}
disabled={!input.trim() && pendingFiles.length === 0}
- aria-label="Send message"
+ aria-label={isLoading ? "Add to what it's working on" : "Send message"}
className="flex-shrink-0 w-11 h-11 rounded-xl bg-accent-strong hover:bg-accent-strong/90 disabled:opacity-30 disabled:cursor-not-allowed transition-all duration-150 flex items-center justify-center cursor-pointer"
>
<Icon name="arrow-send" size="w-4 h-4" className="text-white" />
diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.ts
index 9dd1acd1..93db7c9f 100644
--- a/packages/ui/src/lib/api.ts
+++ b/packages/ui/src/lib/api.ts
@@ -137,13 +137,21 @@ export interface SourcesEvent extends AnswerSources {
session_id?: string;
}
+// The running turn took messages the user sent while it worked (POST
+// /chat/add), named by the ids the client gave them.
+export interface MessageAdded {
+ type: "message_added";
+ ids: string[];
+}
+
export type StreamItem =
| ChatChunk
| DebugEvent
| ActionTaken
| FormPatch
| Activity
- | SourcesEvent;
+ | SourcesEvent
+ | MessageAdded;
export interface StreamChatOptions {
committeeReview?: boolean;
@@ -269,6 +277,30 @@ export async function stopChat(clientTurnId: string): Promise<boolean> {
}
}
+// Hand a message to the turn that is still running, so its answer takes it
+// into account. False when the turn won't take it (finished, stopped, full):
+// the caller then sends it as the next turn.
+export async function addChatMessage(
+ clientTurnId: string,
+ messageId: string,
+ message: string,
+): Promise<boolean> {
+ try {
+ const res = await fetch(`${API_BASE}/chat/add`, {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ client_turn_id: clientTurnId,
+ message_id: messageId,
+ message,
+ }),
+ });
+ return res.ok;
+ } catch {
+ return false;
+ }
+}
+
export interface OnboardStatus {
session_id: string;
// The step's place among the steps this wizard asks (a solo workspace
diff --git a/packages/ui/src/lib/queuedMessages.ts b/packages/ui/src/lib/queuedMessages.ts
new file mode 100644
index 00000000..c7a653af
--- /dev/null
+++ b/packages/ui/src/lib/queuedMessages.ts
@@ -0,0 +1,42 @@
+// Messages typed while the Executive is still working on a turn. Each one is
+// handed to the running turn (POST /chat/add), which takes it at its next step
+// and says so with a `message_added` event. When the turn ends, the ones it
+// took are shown as part of that exchange, and the rest are sent as the next
+// turn, so nothing is lost and nothing is answered twice.
+
+export interface QueuedMessage {
+ id: string;
+ text: string;
+ // The running turn took it into its answer.
+ taken: boolean;
+}
+
+export function markTaken(queued: QueuedMessage[], ids: string[]): QueuedMessage[] {
+ if (ids.length === 0) return queued;
+ const set = new Set(ids);
+ return queued.map((m) => (set.has(m.id) ? { ...m, taken: true } : m));
+}
+
+export interface SettledQueue {
+ // Shown as the user's own bubbles, after the turn's message and before the
+ // reply that answered them.
+ taken: string[];
+ // Sent together as the next turn; null when there is nothing left.
+ next: string | null;
+}
+
+// How a turn that produced a reply settles its queue.
+export function settleQueue(queued: QueuedMessage[]): SettledQueue {
+ const left = queued.filter((m) => !m.taken).map((m) => m.text);
+ return {
+ taken: queued.filter((m) => m.taken).map((m) => m.text),
+ next: left.length ? left.join("\n\n") : null,
+ };
+}
+
+// A turn that ended with nothing saved (stopped before any output, or
+// failed) keeps none of it: everything goes back into the composer, after
+// whatever is being returned there already.
+export function composerText(first: string, queued: QueuedMessage[]): string {
+ return [first, ...queued.map((m) => m.text)].filter((t) => t.trim()).join("\n\n");
+}