AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
fix(chat): tell the model the current date and time on every chat turn (#580)
ladislav-urban1196957372f2
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex 03fe5ffc..a6d860c0 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -118,6 +118,7 @@ system:- A teammate's own conversations with the Executive are private to them too. Every audit row of a turn a non-principal team member speaks on a verified surface, or by email Gmail authenticated as theirs, carries private_to_person (people_tools.teammate_turn_owner via audit_row_owner; the pre-bind rows via rows_for_person in audit_rows_on_senders_turn, the web chat route and the email poller). An unproven sender keeps the ordinary rule so a forged From can't hide a turn from the principal. The /audit read routes give the principal every row, a team member's own (their turns, Act as me, history notes) as an action only (api.routes.audit._redact: rebuilt summary naming the tool and whose conversation, safe details only, no full payload, left out of text search), and anyone else (once a principal exists) only their own rows in full (api.routes.audit._view, AuditLogger only_owned / all_owners); /audit/usage is unchanged. A teammate's web chat or DM (not a channel or group session, chat._shared_space) opens for its owner alone, the principal included (chat._session_access). A message the Executive sends to someone else on a teammate's turn is linked without its originating session, so the recipient's reply is not hydrated with an excerpt of the teammate's chat (schedule_tools._record_outbound_context).- A web chat its owner shared (session_shares) is one its members write in with the owner, live, and it is no private conversation. Members get the turn's access through chat._shared_member, never its ownership, so they can't delete, rename, rate, share or redo it, and a mail_private chat or a chat-app conversation is never shared. Every turn there sets Session.shared_chat, which turns off Act as me (delegation.settings.private_conversation), the open-loop private surface (open_loop_tools._is_private_surface), a teammate's own mail (teammate_mail._reader_id), the principal's private alert cards, roster requests and find_alerts (briefing.context.render_and_trust) and the principal-only tools (content_trust.principal_only_withheld), because everyone in the chat reads every reply and writes into what the next turn reads. Someone archived is out of every shared chat (chat._shared_member). Live streams are capped per person, per chat and per process. Each person's message reaches the Executive as [Name]: in the history and the current turn, and the note naming who is in the chat rides in channel_context_block, never a cached block. api.chat_live publishes each turn to the pages that have the chat open (GET /sessions/{id}/live); it is in-process, holds nothing on disk, and a page that reconnects reads the saved chat.- In a shared web chat the note in channel_context_block names the chat's owner and says the others' lines are messages from them, not the owner's instructions. While anyone but the owner has written since the owner's last message (Session.others_spoke_last, from the saved history, the speaker included, true when unreadable), the turn is neither offered nor run SHARED_CHAT_WITHHELD_TOOLS (direct messages, broadcasts, meeting invites and cancellations, follow-ups, roster writes, workflow runs, saves and suggestions) nor a gateway mail send, reply, forward or draft or calendar write that mails attendees (schedule_tools.shared_chat_withholds); this holds on the owner's own turn right after another's line too, and the owner's next message with nobody else's in between lifts it.+ - Every chat turn says when it is. _build_messages opens the user turn with a <current_time> hint (_current_time_block - weekday, date, HH.MM, IANA zone and UTC offset, in workspace_settings.get_user_timezone, the briefs' zone). Without it a chat turn had no date and the model guessed one, e.g. from the newest record a tool returned. User turn, never a cached block, since it changes every turn.- The Executive never offers to loop in, DM, or notify the human it is currently talking to. Each chat turn carries a <current_speaker> hint in the user turn (resolved from the caller's person_id, principal-flagged) and the persona "Choosing Who to Tell" rule forbids routing to anyone already in the room — so the principal reading a brief is never told the Executive will "loop Jordan in."- Specialists run in parallel via route_parallel() for cross-domain questions.- The untrusted-content policy (orchestrator.content_trust) is the one rule for text the principal did not write — inbound email, chat, attached files, watched pages. WHO SPEAKS - the principal only when the surface proved it (principal_speaking - web chat as the principal, CLI, their own Slack/Discord or secret-verified Telegram, their own address with Gmail dmarc=pass); an empty origin_channel is never read as trust. MEMORY - episodic extraction only then, and only on words outside <untrusted_content> blocks; peer memory and open loops are recorded under the speaker's own name, never as the principal's. TOOLS - writes on the principal's authority refuse others in their handlers; PRINCIPAL_ONLY_TOOLS (load_mcp_server - it connects the install to any URL; list_saved_tools and run_python_job - the principal's own automations and library files; run_script - it runs code the model just wrote, spending the turn's whole call budget) are not offered unless the principal is speaking on an interactive surface (email excluded, even authenticated), and a call emitted anyway is refused with a not_principal audit row. LABEL - outside text sits in the user turn inside <untrusted_content source author author_verified> with a fixed no-authority notice; NFKC folds compatibility forms, control characters are dropped and the tag's name is renamed wherever the text carries it (any case, spacing, entity-escaped), so the text cannot close its block. The principal's authenticated mail is theirs, but what it quotes or forwards still goes in a block (source email_quoted). A new inbound surface is an entry in this module, not a gate invented at its call site.diff --git a/packages/core/openexecutive/architecture/prebuilt/lifecycle.json b/packages/core/openexecutive/architecture/prebuilt/lifecycle.jsonindex 1f038643..e8699985 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 — and a `<lessons>` block when a lesson the conversation review learned from a miss matches the message, `memory/lessons.py`; see the memory 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). A `<pending_followups>` block lists, for a verified speaker, the follow-ups they scheduled that haven't gone out (up to 10, from `correction_tools.pending_followups_block`, the same ownership rule as `list_followups`), and asks the Executive to cancel one with `cancel_followup` when the message shows it is already done or no longer needed, and say so in a line. 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. The call carries the conversation so far (`Session.get_recent_history`: 20 to 30 turns, its start moving in steps of 10) with a 1h cache marker on the previous reply, so each message reads the earlier conversation from the prompt cache and writes only what is new (see Caching); on the OpenRouter path the translator keeps that marker on the reply's text. The history is re-read from the stored transcript at the start of every web turn, so a chat continued in a chat app and then reopened on the web or phone includes the turns the app added.\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. Each round's text starts a new paragraph after the text streamed before it (`executive._round_separator`), so words the model writes before a tool call never run into its answer; nothing it writes is dropped. 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 a connected (MCP) tool, plain words for what it does (\"Searching Drive…\"), from the same table (`orchestrator/tool_labels.py`) that names the finished chip (\"Searched Drive\"). The raw `server__tool` name never reaches the user. Under the reply, repeats of the same action collapse into one chip with a count, and tapping it lists what each run looked at. 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.\n **Do what it says.** Before the turn ends, its last reply is checked against the tool calls the turn made (`orchestrator/claim_check.py`). A reply with no word that can claim a change (\"done\", \"removed\", \"I'll remind you\"…) ends the turn as before. Otherwise one small forced-tool call on `ROUTING_MODEL` reads the person's message, the reply and each call with the start of its result, and reports a claim of a change no call made (or put up for approval). The claim must appear word for word in the reply, or it is ignored. The loop then gets one more round with a note in the user turn (never a cached block): make the change with the right tool, or say plainly it isn't done. Once a turn; a failed check lets the reply through. On the web chat the extra round streams after the first reply, separated by a blank line; chat apps send the whole reply at once. `CLAIM_CHECK_ENABLED` turns it off.\n **A chat several people are in.** When its owner shared a web chat (`session_shares`), every turn in it is labelled: the history is re-read with each person's message starting `[Name]: `, the current message too, and a note naming everyone in the chat rides in the user turn (`channel_context_block`, never a cached block). The Executive answers whoever wrote the latest message. Such a session is no private conversation (`Session.shared_chat`): Act as me is off there (`delegation.settings.private_conversation`), open loops are not listed as on a private surface, no one's mail is read there, the principal's included (`teammate_mail._reader_id`), what the Executive remembers about the speaker (peer memory) is not fetched, the alert digest leaves out the principal's private cards and roster requests (`briefing.context.render_and_trust`), and the principal-only tools are withheld whoever speaks (`content_trust.principal_only_withheld`), because the others write into what the principal's turn reads. A message that starts like a label (`[Alex]: …`) loses it before its sender's own goes in front. Peer memory still records each person's own words. Turns stay one at a time under the conversation's lock; the route publishes each one to the chat's live stream (`api.chat_live`) as it runs, so everyone else in the chat watches it happen. A chat of one publishes nothing.\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. A verified speaker's turn is also kept for the **conversation review** (`memory.chat_review`, see Memory), which reads it once the chat has been quiet 30 minutes and fixes what the replies left undone, from the speaker's own quoted words. A turn that touched their mailbox, which teaches no other memory, is kept too, for their own review only (`record_turn(mail=...)`: tools by name, no results), with the words they typed rather than the blanked text the other passes get. A replay turn is never kept. 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. A tagged DM is also subject to the recipient's own notification settings: in their quiet hours, or when they chose *In my briefs*, the send handler stores it (`outbound_guard.check_hold`, `people.held_messages`) and returns `{\"status\": \"held\"}` instead of sending (see Org). 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. While nothing else is going out — a slow tool call, a long specialist round — the route sends an SSE comment (`: keepalive`) every `CHAT_STREAM_KEEPALIVE_S` (15 s by default, 0 for none) so a browser or proxy does not drop the connection as idle; the step it waits on keeps running across it, and the whole-turn deadline is unchanged. Every call through the MCP gateway (Gmail, Calendar, Drive, Outlook, OneDrive, tool search) has its own ceiling, `MCP_TOOL_TIMEOUT_S` (120 s): past it the model gets an error saying the tool did not answer and may still have run, so it checks before calling again, and no outbound linkage is recorded for a send that timed out. 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. None of this runs for a **replay** of a graded turn (`Session.replay`, `memory/replay.py`): the loop answers its acting tools with \"done\" and records them on the session, offers no script, job or server load, and skips every post-turn pass, so the nightly replay of the misses changes nothing and reaches nobody. On a team member's turn (`department_gate.speaker`) it also refuses an alert that is not routed to them (`routed_to_person_id`), so they clear only their own items; the principal clears anything on the board. `create_alert` on such a turn ignores the `source`, `external_id` and `from_address` it was given: the alert gets the source `team_member`, a fresh id and `raised_by` (their name), so it can't pose as mail or a watch, coalesce into one, or pre-claim the id a real alert will arrive with.\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. Later turns of that conversation stay private the same way; the pin also records whether the reading turn is still in the history the model is shown (`mail_in_view`, from `sessions.mail_read_at` against `session.history_window_start`), and links, scripts, workflows and posts to everyone stay withheld only while it is.\n\n### Tracing\n\nSet `LOGFIRE_TOKEN` and every step above becomes visible as one Pydantic Logfire trace (`openexecutive.observability`): the `POST /chat` request span, a `messages.create` / `messages.stream` span per model call with its token and prompt-cache counts, a `specialist {name}` span per fan-out branch (siblings overlap, so the slowest one sets the turn's critical path), and a `knowledge retrieve` span per RAG query. Scheduler and workflow model calls appear as their own root traces. Traces record timings, model names and usage only — prompt and reply text, request bodies, path parameters (each request URL is reduced to its route template), query strings, client identity and exception messages (errors are recorded by type) never leave the process, and incoming trace headers are ignored. With the token unset, tracing is off and `get_provider()` returns the bare backend.",+ "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 opens with a `<current_time>` hint: the day, date, time and zone in the workspace's timezone (`workspace_settings.get_user_timezone`, as the briefs use), so relative dates resolve against today instead of a guess; it is in the user turn because it changes every turn. It 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 — and a `<lessons>` block when a lesson the conversation review learned from a miss matches the message, `memory/lessons.py`; see the memory 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). A `<pending_followups>` block lists, for a verified speaker, the follow-ups they scheduled that haven't gone out (up to 10, from `correction_tools.pending_followups_block`, the same ownership rule as `list_followups`), and asks the Executive to cancel one with `cancel_followup` when the message shows it is already done or no longer needed, and say so in a line. 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. The call carries the conversation so far (`Session.get_recent_history`: 20 to 30 turns, its start moving in steps of 10) with a 1h cache marker on the previous reply, so each message reads the earlier conversation from the prompt cache and writes only what is new (see Caching); on the OpenRouter path the translator keeps that marker on the reply's text. The history is re-read from the stored transcript at the start of every web turn, so a chat continued in a chat app and then reopened on the web or phone includes the turns the app added.\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. Each round's text starts a new paragraph after the text streamed before it (`executive._round_separator`), so words the model writes before a tool call never run into its answer; nothing it writes is dropped. 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 a connected (MCP) tool, plain words for what it does (\"Searching Drive…\"), from the same table (`orchestrator/tool_labels.py`) that names the finished chip (\"Searched Drive\"). The raw `server__tool` name never reaches the user. Under the reply, repeats of the same action collapse into one chip with a count, and tapping it lists what each run looked at. 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.\n **Do what it says.** Before the turn ends, its last reply is checked against the tool calls the turn made (`orchestrator/claim_check.py`). A reply with no word that can claim a change (\"done\", \"removed\", \"I'll remind you\"…) ends the turn as before. Otherwise one small forced-tool call on `ROUTING_MODEL` reads the person's message, the reply and each call with the start of its result, and reports a claim of a change no call made (or put up for approval). The claim must appear word for word in the reply, or it is ignored. The loop then gets one more round with a note in the user turn (never a cached block): make the change with the right tool, or say plainly it isn't done. Once a turn; a failed check lets the reply through. On the web chat the extra round streams after the first reply, separated by a blank line; chat apps send the whole reply at once. `CLAIM_CHECK_ENABLED` turns it off.\n **A chat several people are in.** When its owner shared a web chat (`session_shares`), every turn in it is labelled: the history is re-read with each person's message starting `[Name]: `, the current message too, and a note naming everyone in the chat rides in the user turn (`channel_context_block`, never a cached block). The Executive answers whoever wrote the latest message. Such a session is no private conversation (`Session.shared_chat`): Act as me is off there (`delegation.settings.private_conversation`), open loops are not listed as on a private surface, no one's mail is read there, the principal's included (`teammate_mail._reader_id`), what the Executive remembers about the speaker (peer memory) is not fetched, the alert digest leaves out the principal's private cards and roster requests (`briefing.context.render_and_trust`), and the principal-only tools are withheld whoever speaks (`content_trust.principal_only_withheld`), because the others write into what the principal's turn reads. A message that starts like a label (`[Alex]: …`) loses it before its sender's own goes in front. Peer memory still records each person's own words. Turns stay one at a time under the conversation's lock; the route publishes each one to the chat's live stream (`api.chat_live`) as it runs, so everyone else in the chat watches it happen. A chat of one publishes nothing.\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. A verified speaker's turn is also kept for the **conversation review** (`memory.chat_review`, see Memory), which reads it once the chat has been quiet 30 minutes and fixes what the replies left undone, from the speaker's own quoted words. A turn that touched their mailbox, which teaches no other memory, is kept too, for their own review only (`record_turn(mail=...)`: tools by name, no results), with the words they typed rather than the blanked text the other passes get. A replay turn is never kept. 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. A tagged DM is also subject to the recipient's own notification settings: in their quiet hours, or when they chose *In my briefs*, the send handler stores it (`outbound_guard.check_hold`, `people.held_messages`) and returns `{\"status\": \"held\"}` instead of sending (see Org). 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. While nothing else is going out — a slow tool call, a long specialist round — the route sends an SSE comment (`: keepalive`) every `CHAT_STREAM_KEEPALIVE_S` (15 s by default, 0 for none) so a browser or proxy does not drop the connection as idle; the step it waits on keeps running across it, and the whole-turn deadline is unchanged. Every call through the MCP gateway (Gmail, Calendar, Drive, Outlook, OneDrive, tool search) has its own ceiling, `MCP_TOOL_TIMEOUT_S` (120 s): past it the model gets an error saying the tool did not answer and may still have run, so it checks before calling again, and no outbound linkage is recorded for a send that timed out. 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. None of this runs for a **replay** of a graded turn (`Session.replay`, `memory/replay.py`): the loop answers its acting tools with \"done\" and records them on the session, offers no script, job or server load, and skips every post-turn pass, so the nightly replay of the misses changes nothing and reaches nobody. On a team member's turn (`department_gate.speaker`) it also refuses an alert that is not routed to them (`routed_to_person_id`), so they clear only their own items; the principal clears anything on the board. `create_alert` on such a turn ignores the `source`, `external_id` and `from_address` it was given: the alert gets the source `team_member`, a fresh id and `raised_by` (their name), so it can't pose as mail or a watch, coalesce into one, or pre-claim the id a real alert will arrive with.\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. Later turns of that conversation stay private the same way; the pin also records whether the reading turn is still in the history the model is shown (`mail_in_view`, from `sessions.mail_read_at` against `session.history_window_start`), and links, scripts, workflows and posts to everyone stay withheld only while it is.\n\n### Tracing\n\nSet `LOGFIRE_TOKEN` and every step above becomes visible as one Pydantic Logfire trace (`openexecutive.observability`): the `POST /chat` request span, a `messages.create` / `messages.stream` span per model call with its token and prompt-cache counts, a `specialist {name}` span per fan-out branch (siblings overlap, so the slowest one sets the turn's critical path), and a `knowledge retrieve` span per RAG query. Scheduler and workflow model calls appear as their own root traces. Traces record timings, model names and usage only — prompt and reply text, request bodies, path parameters (each request URL is reduced to its route template), query strings, client identity and exception messages (errors are recorded by type) never leave the process, and incoming trace headers are ignored. With the token unset, tracing is off and `get_provider()` returns the bare backend.","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-20T16:25:55+00:00"}diff --git a/packages/core/openexecutive/evals/_scenarios/operations_003.yaml b/packages/core/openexecutive/evals/_scenarios/operations_003.yamlnew file mode 100644index 00000000..c8722c24--- /dev/null+++ b/packages/core/openexecutive/evals/_scenarios/operations_003.yaml@@ -0,0 +1,16 @@+id: operations_003+domain: operations+description: "Principal asks for today's date and a deadline relative to it; the Executive must take the date from the turn's <current_time> rather than guess it or say it cannot know"+company_context:+ stage: "Seed"+ industry: "Wholesale distribution"+ headcount: 12+query: "What's today's date? And if a supplier gives us net 30 from today, which date is the payment due, and what weekday is that?"+expected_topics:+ - current_date+ - payment_terms+quality_criteria:+ states_a_specific_current_date_and_weekday: true+ due_date_is_thirty_days_after_the_stated_date: true+ weekday_matches_the_due_date: true+ does_not_say_it_cannot_know_the_date: truediff --git a/packages/core/openexecutive/orchestrator/executive.py b/packages/core/openexecutive/orchestrator/executive.pyindex 57c7bfd5..d17a62ea 100644--- a/packages/core/openexecutive/orchestrator/executive.py+++ b/packages/core/openexecutive/orchestrator/executive.py@@ -9,6 +9,7 @@ import reimport timeimport uuidfrom collections.abc import AsyncIterator+from datetime import UTC, datetimefrom typing import Anyfrom openexecutive.audit import bind_turn, clear_turn, private_rows, set_turn@@ -715,6 +716,26 @@ def _drive_memory_block(session: Session, person_id: int | None) -> str:return ""+def _current_time_block(now: datetime | None = None) -> str:+ """Render the body of a <current_time> hint: when this turn is, in the+ workspace's timezone (``get_user_timezone``, as the briefs use).++ Without it a chat turn carries no date at all, so the model guesses one,+ for instance from the newest record a tool returned, and "yesterday",+ "this week" or "overdue" resolve against the wrong day.+ """+ from openexecutive.memory.workspace_settings import get_user_timezone++ zone = get_user_timezone()+ local = (now or datetime.now(UTC)).astimezone(zone)+ offset = local.strftime("%z")+ return (+ f"{local:%A} {local.day} {local:%B %Y}, {local:%H:%M} "+ f"({getattr(zone, 'key', None) or local.tzname()}, UTC{offset[:3]}:{offset[3:]}). "+ "Resolve today, yesterday, this week, this month and other relative dates against this."+ )++def _build_current_speaker_block(person_id: int | None) -> str | None:"""Render the body of a <current_speaker> hint naming who is in the room.@@ -1109,6 +1130,12 @@ class Executive:user_content_parts: list[dict[str, Any]] = []+ # When this turn is, so relative dates resolve against today rather+ # than a guess. Changes every turn, so the user turn, never a cached+ # system block.+ user_content_parts.append(+ {"type": "text", "text": f"<current_time>\n{_current_time_block()}\n</current_time>"}+ )# Name the human in the room first so the model never offers to loop# in / DM the person it is replying to. Lives in the user turn (never# the cached system block) since the speaker varies per request.diff --git a/packages/core/tests/unit/test_executive_current_time.py b/packages/core/tests/unit/test_executive_current_time.pynew file mode 100644index 00000000..6435099c--- /dev/null+++ b/packages/core/tests/unit/test_executive_current_time.py@@ -0,0 +1,72 @@+"""A chat turn says when it is. Without a <current_time> hint the model has no+date at all and guesses one (from the newest record a tool returned, say), so+"yesterday" or "this month" resolve against the wrong day. _build_messages+puts it in the user turn, in the workspace's timezone, never in a cached+system block. See openexecutive.orchestrator.executive.+"""+from __future__ import annotations++import os+from datetime import UTC, datetime+from unittest.mock import patch+from zoneinfo import ZoneInfo++os.environ.setdefault("ANTHROPIC_API_KEY", "sk-test-not-used")+++def _time_text(content: list[dict]) -> str | None:+ for part in content:+ text = part.get("text", "")+ if "<current_time>" in text:+ return text+ return None+++def test_the_block_names_the_day_date_time_and_zone() -> None:+ from openexecutive.orchestrator.executive import _current_time_block++ noon_utc = datetime(2026, 10, 20, 12, 35, tzinfo=UTC)+ with patch("openexecutive.memory.workspace_settings.get_user_timezone", return_value=ZoneInfo("Europe/Prague")):+ block = _current_time_block(noon_utc)+ assert block.startswith("Tuesday 20 October 2026, 14:35 (Europe/Prague, UTC+02:00).")+ assert "yesterday" in block+++def test_the_date_is_where_the_workspace_is_not_utc() -> None:+ # Late evening in Los Angeles is already tomorrow in UTC: "today" is+ # the workspace's day.+ from openexecutive.orchestrator.executive import _current_time_block++ late_la = datetime(2026, 10, 21, 5, 30, tzinfo=UTC)+ with patch(+ "openexecutive.memory.workspace_settings.get_user_timezone", return_value=ZoneInfo("America/Los_Angeles")+ ):+ block = _current_time_block(late_la)+ assert block.startswith("Tuesday 20 October 2026, 22:30 (America/Los_Angeles, UTC-07:00).")+++def test_every_chat_turn_carries_it_first_in_the_user_turn() -> None:+ from openexecutive.orchestrator.executive import Executive+ from openexecutive.orchestrator.session import Session++ messages = Executive()._build_messages(Session(session_id="t-time-1"), "what were yesterday's sales?")+ content = messages[-1]["content"]+ block = _time_text(content)+ assert block is not None, "no <current_time> block in the user turn"+ assert content[0]["text"] == block+ assert block.rstrip().endswith("</current_time>")+ # The person's words still come last.+ assert content[-1]["text"] == "what were yesterday's sales?"+++def test_it_never_goes_in_the_cached_system_prompt() -> None:+ # The time changes every turn: in a cached block it would break caching,+ # so the blocks built a minute apart are the same.+ from openexecutive.prompts.cache_manager import build_system_blocks++ first = build_system_blocks()+ with patch("openexecutive.orchestrator.executive.datetime") as clock:+ clock.now.return_value = datetime(2030, 1, 1, tzinfo=UTC)+ later = build_system_blocks()+ assert first == later+ assert all("<current_time>" not in block.get("text", "") for block in first)