AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
feat(agents): offer Direct, Supportive and Analytical voices in setup and Settings (#310)
Rufusc99d9d1edcc2
diff --git a/.gitignore b/.gitignoreindex cc199c15..c999b979 100644--- a/.gitignore+++ b/.gitignore@@ -76,6 +76,9 @@ evals/results/# Anvil~/.claude/anvil/*.db+*.db-wal+*.db-shm+*.db-journalpackages/ui/tsconfig.tsbuildinfo# Private deployment substrate. These describe one specific hosting setup anddiff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex b57ab337..36a18d40 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -485,6 +485,22 @@ providers:preset from the overrides: ``active`` when every agent matches,otherwise null ("Custom") with ``base`` (the preset most agents match,Balanced on a tie) and ``custom_agents`` (the agents that differ).+ executive_voices: |+ The Executive's voice persona (personas/builtin/*.md, shadowed by+ voice_personas rows) is substituted into block 0 at {VOICE_PERSONA}.+ Three general voices are offered by the shared VoicePicker in setup+ (/onboard, after the workspace choice and solo role step) and Settings ->+ Executive, saving voice_persona_slug through PATCH /agents/executive:+ Direct (slug ``default``, stored as no override), Supportive and+ Analytical. Frontmatter ``description`` / ``sample`` feed the picker;+ ``legacy: true`` marks the named-executive voices, hidden from the picker+ but still loadable (PersonaMeta.is_legacy), so existing picks keep+ working. Voice files hold disposition only; length rules live in+ prompts/executive_persona.py, enforced by test_voice_picker. Eval+ scenarios may set ``voice_persona`` (validated by+ evals.scenarios.scenario_voice_persona), carried on+ Session.voice_persona_slug, which wins over the install override for+ that session only, like workspace_mode and principal_role.per_specialist_research_focus: |Each consult-routable specialist (cso, cfo, cmo, coo, chro, cpo, gc) has aCouncil-editable ``research_focus`` override — the per-domain scope taildiff --git a/packages/core/openexecutive/architecture/prebuilt/agents.json b/packages/core/openexecutive/architecture/prebuilt/agents.jsonindex e9ab713d..b9ee2c57 100644--- a/packages/core/openexecutive/architecture/prebuilt/agents.json+++ b/packages/core/openexecutive/architecture/prebuilt/agents.json@@ -1,7 +1,7 @@{"section_id": "agents","title": "Agent Council",- "markdown": "The Executive (`openexecutive.orchestrator.executive.Executive`) is a single coherent persona that fans out to specialist sub-agents via Anthropic tool use. Each specialist subclasses `openexecutive.agents.base.BaseAgent`, carrying a `name`, `domain`, and `model`, and exposes `analyze(...)`, which wraps the question in user-turn context and calls Claude through the per-call provider. That context is per call and never cached: `<company_stage>` (the stage from the company profile — specialists never see the profile itself), in solo mode `<principal_role>` (what kind of principal the advice is for, in plain words, with their title and remit — `router.principal_role_context`), `<department_memory>`, `<past_decisions>`, `<failure_cases>`, `<relevant_knowledge>` and `<conversation_context>`, outermost first. The specialist's own system prompt is a static domain constant under one `cache_control` block, so it stays byte-identical across companies and profile edits. A chat turn takes the stage from its session's profile (the one the Executive reasons over, and the one an eval scenario injects); workflow steps and the MCP server's `consult_specialist` read it fresh from the profile on disk. The role tag follows the turn's mode: a chat turn pins the role on its session with the mode (`pin_turn_principal_role`: the session's `principal_role` override, else the workspace settings) and sends it in solo and nothing in team, so the org block, every specialist in the turn and any workflow the turn starts see the same role; callers with no chat turn read it fresh (`load_principal_role`: the current session's mode and role, else the workspace's), and a failed read sends no tag rather than failing the consult. The CFO, CSO and sales prompts key their advice on it: for a bootstrapped, self-funded or solo company they drop venture fundraising benchmarks and work from cash, and raise only if the founder wants to.\n\nRouting uses one `consult_specialist` tool. Beside it the Executive carries its skill tools (`search_skills`, `load_skill`, `create_skill`, `update_skill`, `delete_skill` — shown to users as **playbooks**; `create_skill` / `update_skill` / `delete_skill` never change the library — they save a draft (`knowledge/skill_drafts.py`) that a person approves on the Playbooks tab, and the reply links to it; `update_skill` / `delete_skill` (and `create_skill`, for a name a workflow still follows) refuse any built-in name (including a company's customized copy) and any company playbook a workflow (even a switched-off custom one) follows — workflows read playbooks at run time, approved scheduled ones included, and this loop also runs on inbound email and chat, so only a person on the Playbooks tab can change what a workflow follows; a hidden built-in is invisible to search and load; each `search_skills` hit lists the `workflows` that follow it, and the persona routes \"the finished deliverable\" to that workflow and quick or partial asks to the playbook inline); Tool calls made while proactive work is tagged (scheduler dispatch, reflection, research, alert review) feed the Attunement outcome ledger. Goals have three tools: `list_department_goals`, `update_department_goal` (progress the user reports) and `create_goal` (a new goal the principal states, filed under an area by slug or title and creating the area when none matches — see Org). `create_goal` runs only for the principal on a verified surface, and no unattended run is offered it: the tools in `schedule_tools.UNATTENDED_WITHHELD_TOOLS` are dropped from reflection's and research's toolkits by `unattended_toolkit`, and from the chat loop when its Session is marked `unattended` — the scheduler's PROACTIVE TRIGGER run, whose prompt quotes stored intent text; a call the model emits anyway gets an error tool_result. `record_decision_outcome` records how a past decision turned out — the weekly review lists decisions older than 30 days with no outcome as `[decision N]` — writing `decisions.outcome` (`episodic.update_decision`) and auditing the rationale; it has `create_goal`'s gate (the principal on a verified surface only; everyone else gets an audited refusal) and is in `UNATTENDED_WITHHELD_TOOLS` too. A missing or unknown id returns the decisions still waiting on an outcome, so the model can retry with the right one. Its schema is static; the solo persona has one line on it, and team mode learns it from the tool description, so the team persona is byte-identical. Attunement adds `list_open_loops` (what a person owes — everyone's for the principal only in a private conversation, otherwise the caller's own) and `close_open_loop`, which only closes a loop when the turn's resolved speaker is the principal or the loop's owner — an unrostered sender, a signed-in web user not on the roster, and unattended sessions are refused. `assign_open_loop` opens one on request (\"ask Ben to send me the Q3 numbers by Friday\") for the principal or a rostered teammate on a verified surface — never an email, a turn private to the principal or an unattended run, which are also withheld the tool — and only when `task` appears verbatim in what the speaker typed this turn, at most 5 per turn; that turn's extraction pass then opens no second loop for the same owner. The roster write tools (`upsert_person`, `archive_person`, `set_department_head`) are the principal's alone, and only on a surface that verified the speaker — the web chat, the principal's own Slack or Discord, or a private Telegram chat when `TELEGRAM_WEBHOOK_SECRET` is set to a value Telegram can send (Telegram identifies the chat rather than the sender, and without that secret its webhook accepts anyone's update). A teammate, an email (even from the principal's address), Google Chat, the CLI, the MCP server and unattended runs get `status: refused` (audited, and no action chip), because a team member's People row is also the web sign-in and outbound-email allow-list. `upsert_person` takes `kind` (`team` / `contact`; a new person defaults to `contact` in solo mode, an update keeps the current kind) and `email_aliases` (other addresses the person writes from — the full list, replacing the current one; they match mail and may be emailed but never sign in, and one already on someone else is refused), and after every write any pending roster request whose sender now matches someone is closed and its held messages replayed. `resolve_roster_request` answers a **roster request** — someone not on the People list who wrote in and is waiting (see Org): `approve` (a new person; `kind` defaults to team for a company-domain sender, else contact, when the principal did not say), `link` (someone already listed, by `person_id`; `replace_channel_id` only when the principal said so) or `decline`. It has the roster tools' gate (the principal on a verified surface; audited refusal otherwise), is in `UNATTENDED_WITHHELD_TOOLS`, and answers only an id in `Session.trusted_roster_request_ids` — the ids the server printed that turn in a `<roster_requests>` block (`briefing.context.format_roster_requests_for_prompt`, up to 10 pending requests), which `render_and_trust` appends to the `<briefing>` digest on the principal's own verified turn only and records on the session in the same step, so an id the model invents or reads out of a message adds nobody. Each line is server-derived — id, channel, address or account id, the sender's name sanitised and marked unverified, a company-domain hint, the message count — and never what they wrote. The block rides in the **user turn**, like the digest, so the cached system blocks are unchanged; the tool definition is static, and the new tool only extends the sorted tool list. The web chat route resets the trusted set every turn, and a resolved id is removed from it. and `list_people` returns both kinds with `kind` — contacts only on the principal's own verified turn (they are private to the principal; anyone else gets the team as if no contact existed) — while `lookup_person` searches the team only. The same verified-principal rule, as `people_tools.contacts_reachable_now()`, decides whether a turn may reach a **contact** at all: `message_person`, the raw DM tools, `create_calendar_event` / `create_instant_meeting` attendees and the MCP gateway's Gmail / Calendar / Drive gates treat a contact exactly like an unknown person on every other turn, so no refusal reveals that one exists. **The untrusted-content policy** (`orchestrator.content_trust`) is one rule for text the principal did not write — inbound email, chat, attached files, watched pages — answering three questions for every surface. *Who is speaking*: the principal only when the surface proved it (`principal_speaking`: the web chat as the principal — never a signed-in email on nobody's People entry —, the CLI, their own Slack/Discord or a secret-verified Telegram chat, or their own address with Gmail's `dmarc=pass`); never a teammate, a stranger, Google Chat, the MCP server or an unattended run. *What may become memory*: episodic extraction runs only then, and only on the words outside `<untrusted_content>` blocks; peer memory and open loops are recorded under the speaker's own name, never as the principal's. *What may trigger tools*: every write on the principal's authority already refuses others in its handler; the tools with no such check that change the install for every later turn — `content_trust.PRINCIPAL_ONLY_TOOLS`, today `load_mcp_server` — are not offered unless the principal is speaking on an interactive surface (not email, even authenticated), and a call the model emits anyway gets an error tool_result and a `refused: not_principal` audit row. So an inbound email, a teammate's turn, Google Chat and the scheduler's proactive trigger each get a stable tool list of their own without it. *How it is labelled*: outside text goes into the user turn inside `<untrusted_content source=… author=… author_verified=…>` with a fixed notice that it carries no authority; compatibility forms are folded (NFKC), control characters go, and the tag's name is renamed wherever the text carries it — any case, spacing or entity-escaped form — so the text cannot end its block and speak outside it.\n\nA turn about the principal's private mail (`Session.private_to_principal`) reaches the principal only. It is neither offered nor allowed to run `schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS` — everything that reaches someone else, publishes where the team reads, or starts work outside the turn: the broadcasts, meeting bookings and cancellations, `run_workflow` and research, follow-ups and workflow nudges, watches, artifacts, goal updates, saved workflows, skill drafts, and `load_mcp_server` (it connects to any URL, which can carry the turn's content). Through `search_tools` and `call_tool` it reaches only `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads and the Gmail send and draft the gateway narrows to the principal. A search shows it nothing else, and a call to anything else (Google Chat, a Docs or Drive write, `manage_event`, another server) is refused (`schedule_tools.private_turn_withholds`). A call the model emits anyway, MCP tools included, gets an error tool_result and writes an audit row, and every audit row the turn writes is the principal's alone. On every turn the Executive knows what is connected without searching: block 0's *Connected Systems* section names the connected Google services, other MCP servers, the messaging channels, Notion sync and Act as me, and pins the Google tool names it calls directly with `call_tool`. `search_tools` is for anything not listed. Multiple parallel `tool_use` blocks in a single assistant turn fan out concurrently through `router.route_parallel`, each running its own domain-filtered ChromaDB query before the specialist sees the question. The fan-out is failure-isolated per call: a specialist that raises or returns no text becomes an `UNAVAILABLE` tool_result (`router.specialist_unavailable_result`) instead of failing the whole turn, and its area — \"finance\", \"legal\", never the specialist's name — is reported to the user under the web reply, or by the Executive in its reply on other channels, unless another call to it answered that turn. A failed specialist does not count as consulted, so it takes no committee seat. Cancellation (Stop) still propagates. The Executive then synthesizes the returned analyses into one reply.\n\n`remember_fact`, `forget_fact` and `update_company_profile` (`orchestrator/fact_tools.py`) make a correction stick: the first two keep or retire a standing fact in `memory.facts`, and the third changes one field of the company profile. They share `record_decision_outcome`'s gate (the principal on a verified surface, an audited refusal for everyone else) and are in `UNATTENDED_WITHHELD_TOOLS`. `remember_fact` alone also admits a rostered teammate on a verified surface (web signed in, their own Slack or Discord): the fact is stored attributed (`recorded_by_role=\"teammate\"`, rendered `(per <name>)`), and is held as a `proposed` row (`awaiting_approval`) until the principal approves it, unless the principal marked that teammate trusted (\"needs my approval\" off; on by default) — and even then when it would replace the principal's fact. All three are also in `PRIVATE_TURN_WITHHELD_TOOLS`, since what they write or retire is read on everyone's turns. On the principal's own authenticated email (primary address, with Gmail's own `Authentication-Results` reporting `dmarc=pass`, not forwarded) the three tools check the request as usual, then hold it as `awaiting_confirmation`. It applies only when the principal replies to a one-time token emailed to their own address (`integrations.fact_confirmation`); the split into a check step and an `apply_*` step lets chat and the confirmed reply share one apply path. Each write also needs a `source_quote` found in the speaker's own words this turn. The active facts reach every specialist as a `<standing_facts>` user-turn tag: `route_to_specialist` reads them (None → the store, \"\" → none) for chat consults and workflow steps alike, and `BaseAgent.analyze` places the tag next to `<past_decisions>`, never in the cached specialist system prompt.\n\nThe ten entries in `SPECIALIST_REGISTRY` (`openexecutive.orchestrator.router`):\n\n| Key | Agent | Domain |\n| --- | --- | --- |\n| `cso` | `StrategyAgent` | strategy |\n| `cfo` | `FinanceAgent` | finance |\n| `chro` | `HRAgent` | hr |\n| `gc` | `LegalAgent` | legal |\n| `coo` | `OperationsAgent` | operations |\n| `cmo` | `MarketingAgent` | marketing |\n| `cpo` | `ProductAgent` | product |\n| `sales` | `SalesAgent` | sales |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5`; a deep-reasoning tier uses `claude-opus-5` (adaptive thinking); routing/fast classification uses `claude-haiku-4-5`. The Council's **Deep reasoning** toggle is honoured on Claude Opus/Sonnet (direct or via OpenRouter) and on any OpenRouter model whose live catalog entry supports `reasoning` (today all OpenAI, Gemini, DeepSeek and Grok entries; not Llama) — the request translator turns Anthropic adaptive thinking + effort into OpenRouter's `reasoning` parameter. It is a silent no-op on models that can't reason, and disabled for Haiku, which rejects adaptive thinking. A PDF `document` block is translated too: it becomes an OpenAI `file` part, and OpenRouter requests carrying one add the `file-parser` plugin (`native` for models whose catalog entry lists `file` input, else `PDF_OPENROUTER_ENGINE`, default `mistral-ocr`). `FeatureSpec.supports_pdf_input` gates it per model — off for a local server unless `LOCAL_PDF_INPUT` — and a gated-off PDF becomes a text note rather than vanishing. The Council picks a model in two steps: a **Provider** dropdown (Anthropic, OpenAI, Google, Meta, DeepSeek, xAI, Local, …), then a **Model** dropdown limited to that provider, with readable names (\"Claude Opus 5.5\") and the raw id and serving route shown underneath. The Anthropic group combines the direct Claude models (`claude-fable-5-1`, `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5`) with any Claude generation that exists only on OpenRouter, and never lists a model twice. With `OPENROUTER_ENABLED`, the non-Anthropic entries come from OpenRouter's live `/models` catalog (fetched at startup, refreshed in the background, filtered to tool-capable paid text models from an allowlisted vendor set), falling back to a built-in snapshot if the fetch fails. Every Council agent also takes **additional instructions** (`agent_overrides.instructions`): text appended after its prompt by `agents.overrides.append_instructions` inside an `<additional_instructions>` block. `BaseAgent.base_system_prompt()` is the built-in prompt or its full replacement (what the Council's editor shows); `effective_system_prompt()` is that plus the instructions (what every call sends), and the Executive gets the same text through `build_system_blocks(persona_instructions=…)`. Unlike a replaced prompt, instructions leave the agent on its built-in prompt, so prompt improvements keep reaching it. A **Quality** choice above the agents (`agents.presets`) sets every agent's model and deep reasoning at once: **Fast** puts every agent on a small model (`claude-haiku-4-5`) with deep reasoning off, **Balanced** returns each agent to its built-in defaults, and **Thorough** puts the Executive and the domain specialists on the largest allowed model (`claude-opus-5-5`, else `claude-opus-5`) with deep reasoning on where the model supports it, leaving triage and the helpers below on their defaults. Presets change quality only; they never cap spend. Each preset resolves against the install's model allowlist at request time and is offered only when one of its models is allowed. Applying one writes ordinary per-agent overrides (model and deep reasoning only), so history, rollback and later per-agent edits keep working; an agent changed on its own afterwards shows as **Custom**. Eight Council-only agents are model/prompt-overridable in the UI but NOT callable via `consult_specialist`, because they are deliberately kept out of `SPECIALIST_REGISTRY`: `quality_judge` (committee review), `utility_fast` (gates, titles, decision parsing), `research` (the `executive_research` fan-out), `fixture_generator` (invents demo companies), `engagement_intake` (models a real client from intake material), `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments), `workflow_designer` (runs the conversational New workflow wizard on `/jobs/new`: searches the available tools, asks clarifying questions, then drafts a validated dynamic-workflow definition for the user to review), and `workflow_actor` (runs a workflow's `action` steps: a bounded tool-use loop limited to the tools the user approved for that step). `fixture_generator`, `engagement_intake` and `onboarding_interviewer` share one shape — a forced tool call producing a whole company, validated for referential integrity, with a single repair retry — but opposite epistemics: the fixture author invents, the other two extract and leave unstated facts empty rather than guessing. When the workspace is in solo mode, `onboarding_interviewer`'s first user turn is prefixed with a short hint (`interview.solo_hint(role_kind)`, one static constant per role kind from the onboarding role step): the draft names only the principal, as principal, and no departments; an owner is asked about the offer, customers, pricing, cash and runway, an in-house executive about their organisation (drafted as the company — their employer), function, remit, manager, team size as context and what they are measured on, an independent about their practice, clients and pricing, and with no role given the role-neutral `SOLO_HINT` asks which they are. The hint rides in the user turn and the tool array is unchanged, so the cached system prompt and tool prefix are the same in both modes.\n\nOne more structured-output utility agent sits beside `triage`: `openexecutive.agents.alert_review.AlertReviewAgent` (routing model, one forced `emit_alert_reviews` tool call, never raises). The alert review job hands it a batch of open alerts with evidence and gets back, per alert, a verdict (relevant / changed / resolved / stale), a confidence, the evidence it relied on, a one-line note, why-now, an optional deadline, and a recommended move (none / route / nudge / escalate / draft / suggest_workflow / merge / close) with its parameters. Like `triage`, it never mutates state — `alerts.review.apply_verdict` executes the verdicts deterministically within authority, so the model's job is judgment, not action.\n\n**Solo mode.** When the workspace (or the turn's session) is solo — one person using Open Executive for themselves — the Executive works for that one person, the principal, whatever their role: they may run their own business, lead a function inside a larger organisation, or work independently, and the persona reads which from the context instead of assuming it — the role lines under \"Your Principal\" in the org block, when the principal gave their role (workspace settings: kind, title, reports to, remit, measured on). Its persona swaps the team sections (\"You Are a Member of This Executive Team\", \"Choosing Who to Tell\", \"Departments & Org Coordination\") for \"You Work for One Person\", \"The People in Their World\", \"Who Hears From You\" and \"Goals and Areas\". Solo means only the principal uses Open Executive — not that they have no people: their manager, direct reports, peers, clients, investors and board are contacts. The Executive helps the principal work with them (a 1:1 or review prep, an update or budget case for their manager or board, a negotiation) but does not coordinate them, contacts them only when the principal asks and only if they are a contact, and never offers to loop the principal in. Every specialist stays relevant — HR for the principal's own reports, board and investor communications for reporting upward. Goals are grouped by *area* (the tools' `department_slug` is the area's slug). The chat loop withholds `send_department_message`, `send_company_broadcast` and `set_department_head` from its tool list, and a call to one of them anyway gets a JSON error tool_result instead of running. The mode is resolved once per turn and pinned on the session, so the persona, the org block, the tools and every tool handler agree — a switch made mid-turn applies from the next turn. Team mode is unchanged.\n\nEvery specialist *advises* — each returns domain analysis the Executive synthesizes into one voice. None of them act on the company's behalf; the side-effecting tools in the main loop (schedule, people, departments, broadcast, watchlist, workflows) belong to the Executive, not to a specialist.\n\nOne tool writes under someone else's name, and it is fenced in code rather than the prompt. `ghostwrite_email` (**Act as me**, `orchestrator.delegation_tools`) writes an email as the person the Executive is speaking with and saves it as a draft in their own Gmail; it never sends. It lives in its own registry, never `_ALL_SKILL_TOOLS`, so reflection, research and workflow toolkits can never carry it. The chat loop adds it only on a turn `delegation.settings.pin_turn_delegation` offered it to — the principal, with it on, verified, in a conversation private to them (the web chat, a Slack or Discord DM, a verified private Telegram chat), on an attended turn — and builds that turn's handler map from both registries, so on any other turn a call to it is an unknown tool. Recipients are chosen in code, never by the model, and the text comes from the **ghostwriter** (`delegation.ghostwriter`), a tool-less call with a constant prompt plus the person's \"How I write\" profile. The ghostwriter is deliberately not a Council agent: the Council's edit routes have no principal check. See **Act as Me (Delegation)**.\n\nThe Executive can also launch *any* workflow conversationally: `orchestrator.workflow_run_tools` adds `list_workflows` (the launchable catalog with each workflow's inputs) and `run_workflow` (runs a built-in or custom workflow to completion and returns its artifact, checkpointing approval gates as `awaiting_human`). `run_workflow` runs the weekly review, and in solo mode the morning brief, only for the principal on a verified surface (`Workflow.principal_only_modes`, `create_goal`'s rule); anyone else gets an audited refusal that does not name the rule. A run whose `result` event reports `private_to_principal` (the morning brief on the principal's own verified turn, when it read their private rows) still returns its artifact into that turn, but the stored run keeps `persistence.PRIVATE_RUN_ARTIFACT` instead of the text, since run history is readable by everyone signed in. This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nDeliverables are first-class too. `orchestrator.artifact_tools` gives the Executive three tools: `draft_artifact` publishes a memo, web page (`html`), Word document (`docx`), spreadsheet (`xlsx`, from structured `sheets`) or a `link` to something it created in one of the principal's connected apps through the generic MCP gateway (`search_tools` → `call_tool`, any server — no vendor is named), and returns the artifact's id and link; `list_artifacts` and `get_artifact` let it find and reread its own past work (drafts and workflow outputs alike, through the same `artifact_records` read model the API uses). Revising is `draft_artifact(supersedes=<id>)`, which archives the earlier version. When the principal asks for a deliverable the tool is always used; the \"quiet is the right default\" bar applies only to unprompted drafts. The format enum is a hard-coded sorted tuple so the cached tool schema stays byte-stable. Delivery: `message_person(person_id, text, artifact_id?)` appends the artifact's title and a `UI_BASE_URL/artifacts/<id>` link (through the same outbound guard as any DM; the link needs Open Executive access), and a Gmail send/draft can attach the file itself by `artifact_id` — see Integrations.\n\nDocuments come in the other way through `read_document` (`orchestrator.document_tools`): it reads a PDF, Word, Excel, CSV, Markdown or text file by `path` — one another tool saved, such as a Gmail attachment (`get_gmail_attachment_content`) or a Drive file (`get_drive_file_download_url`) — or a company document by `filename`, with an optional PDF `pages` range. A scanned PDF is converted (`knowledge.pdf_reader`: local OCR by default; with `PDF_PROVIDER_READING=true`, the deployment's own model through its provider's PDF support, falling back to local OCR) rather than returned empty. Reads are confined to the tool download folders — the same resolve-then-contain check as `oe__read_file` — plus the company docs folder, and it is withheld on turns private to the principal (`PRIVATE_TURN_WITHHELD_TOOLS`): those come from a contact's email, whose own attachments the poller has already read into the turn, and must not steer the Executive into company documents.\n\nThe Executive also backs the **Ask OE** panel's form-fill tier via `orchestrator.form_tools.propose_form_values`: when a chat turn arrives with a `<page_context>` block describing a form on the user's screen, the Executive can propose values for it. The proposal is delivered to the UI as a `form_patch` SSE event and placed into the form as highlighted suggestions — the tool never saves or submits anything; the user reviews and saves manually. The tool is **always** in the tool list (tool definitions sit at the top of the cached prompt prefix, so a conditionally-present tool would invalidate the prompt cache whenever panel and non-panel turns alternate); its description restricts usage to turns that carry a form descriptor.",+ "markdown": "The Executive (`openexecutive.orchestrator.executive.Executive`) is a single coherent persona that fans out to specialist sub-agents via Anthropic tool use. Each specialist subclasses `openexecutive.agents.base.BaseAgent`, carrying a `name`, `domain`, and `model`, and exposes `analyze(...)`, which wraps the question in user-turn context and calls Claude through the per-call provider. That context is per call and never cached: `<company_stage>` (the stage from the company profile — specialists never see the profile itself), in solo mode `<principal_role>` (what kind of principal the advice is for, in plain words, with their title and remit — `router.principal_role_context`), `<department_memory>`, `<past_decisions>`, `<failure_cases>`, `<relevant_knowledge>` and `<conversation_context>`, outermost first. The specialist's own system prompt is a static domain constant under one `cache_control` block, so it stays byte-identical across companies and profile edits. A chat turn takes the stage from its session's profile (the one the Executive reasons over, and the one an eval scenario injects); workflow steps and the MCP server's `consult_specialist` read it fresh from the profile on disk. The role tag follows the turn's mode: a chat turn pins the role on its session with the mode (`pin_turn_principal_role`: the session's `principal_role` override, else the workspace settings) and sends it in solo and nothing in team, so the org block, every specialist in the turn and any workflow the turn starts see the same role; callers with no chat turn read it fresh (`load_principal_role`: the current session's mode and role, else the workspace's), and a failed read sends no tag rather than failing the consult. The CFO, CSO and sales prompts key their advice on it: for a bootstrapped, self-funded or solo company they drop venture fundraising benchmarks and work from cash, and raise only if the founder wants to.\n\nRouting uses one `consult_specialist` tool. Beside it the Executive carries its skill tools (`search_skills`, `load_skill`, `create_skill`, `update_skill`, `delete_skill` — shown to users as **playbooks**; `create_skill` / `update_skill` / `delete_skill` never change the library — they save a draft (`knowledge/skill_drafts.py`) that a person approves on the Playbooks tab, and the reply links to it; `update_skill` / `delete_skill` (and `create_skill`, for a name a workflow still follows) refuse any built-in name (including a company's customized copy) and any company playbook a workflow (even a switched-off custom one) follows — workflows read playbooks at run time, approved scheduled ones included, and this loop also runs on inbound email and chat, so only a person on the Playbooks tab can change what a workflow follows; a hidden built-in is invisible to search and load; each `search_skills` hit lists the `workflows` that follow it, and the persona routes \"the finished deliverable\" to that workflow and quick or partial asks to the playbook inline); Tool calls made while proactive work is tagged (scheduler dispatch, reflection, research, alert review) feed the Attunement outcome ledger. Goals have three tools: `list_department_goals`, `update_department_goal` (progress the user reports) and `create_goal` (a new goal the principal states, filed under an area by slug or title and creating the area when none matches — see Org). `create_goal` runs only for the principal on a verified surface, and no unattended run is offered it: the tools in `schedule_tools.UNATTENDED_WITHHELD_TOOLS` are dropped from reflection's and research's toolkits by `unattended_toolkit`, and from the chat loop when its Session is marked `unattended` — the scheduler's PROACTIVE TRIGGER run, whose prompt quotes stored intent text; a call the model emits anyway gets an error tool_result. `record_decision_outcome` records how a past decision turned out — the weekly review lists decisions older than 30 days with no outcome as `[decision N]` — writing `decisions.outcome` (`episodic.update_decision`) and auditing the rationale; it has `create_goal`'s gate (the principal on a verified surface only; everyone else gets an audited refusal) and is in `UNATTENDED_WITHHELD_TOOLS` too. A missing or unknown id returns the decisions still waiting on an outcome, so the model can retry with the right one. Its schema is static; the solo persona has one line on it, and team mode learns it from the tool description, so the team persona is byte-identical. Attunement adds `list_open_loops` (what a person owes — everyone's for the principal only in a private conversation, otherwise the caller's own) and `close_open_loop`, which only closes a loop when the turn's resolved speaker is the principal or the loop's owner — an unrostered sender, a signed-in web user not on the roster, and unattended sessions are refused. `assign_open_loop` opens one on request (\"ask Ben to send me the Q3 numbers by Friday\") for the principal or a rostered teammate on a verified surface — never an email, a turn private to the principal or an unattended run, which are also withheld the tool — and only when `task` appears verbatim in what the speaker typed this turn, at most 5 per turn; that turn's extraction pass then opens no second loop for the same owner. The roster write tools (`upsert_person`, `archive_person`, `set_department_head`) are the principal's alone, and only on a surface that verified the speaker — the web chat, the principal's own Slack or Discord, or a private Telegram chat when `TELEGRAM_WEBHOOK_SECRET` is set to a value Telegram can send (Telegram identifies the chat rather than the sender, and without that secret its webhook accepts anyone's update). A teammate, an email (even from the principal's address), Google Chat, the CLI, the MCP server and unattended runs get `status: refused` (audited, and no action chip), because a team member's People row is also the web sign-in and outbound-email allow-list. `upsert_person` takes `kind` (`team` / `contact`; a new person defaults to `contact` in solo mode, an update keeps the current kind) and `email_aliases` (other addresses the person writes from — the full list, replacing the current one; they match mail and may be emailed but never sign in, and one already on someone else is refused), and after every write any pending roster request whose sender now matches someone is closed and its held messages replayed. `resolve_roster_request` answers a **roster request** — someone not on the People list who wrote in and is waiting (see Org): `approve` (a new person; `kind` defaults to team for a company-domain sender, else contact, when the principal did not say), `link` (someone already listed, by `person_id`; `replace_channel_id` only when the principal said so) or `decline`. It has the roster tools' gate (the principal on a verified surface; audited refusal otherwise), is in `UNATTENDED_WITHHELD_TOOLS`, and answers only an id in `Session.trusted_roster_request_ids` — the ids the server printed that turn in a `<roster_requests>` block (`briefing.context.format_roster_requests_for_prompt`, up to 10 pending requests), which `render_and_trust` appends to the `<briefing>` digest on the principal's own verified turn only and records on the session in the same step, so an id the model invents or reads out of a message adds nobody. Each line is server-derived — id, channel, address or account id, the sender's name sanitised and marked unverified, a company-domain hint, the message count — and never what they wrote. The block rides in the **user turn**, like the digest, so the cached system blocks are unchanged; the tool definition is static, and the new tool only extends the sorted tool list. The web chat route resets the trusted set every turn, and a resolved id is removed from it. and `list_people` returns both kinds with `kind` — contacts only on the principal's own verified turn (they are private to the principal; anyone else gets the team as if no contact existed) — while `lookup_person` searches the team only. The same verified-principal rule, as `people_tools.contacts_reachable_now()`, decides whether a turn may reach a **contact** at all: `message_person`, the raw DM tools, `create_calendar_event` / `create_instant_meeting` attendees and the MCP gateway's Gmail / Calendar / Drive gates treat a contact exactly like an unknown person on every other turn, so no refusal reveals that one exists. **The untrusted-content policy** (`orchestrator.content_trust`) is one rule for text the principal did not write — inbound email, chat, attached files, watched pages — answering three questions for every surface. *Who is speaking*: the principal only when the surface proved it (`principal_speaking`: the web chat as the principal — never a signed-in email on nobody's People entry —, the CLI, their own Slack/Discord or a secret-verified Telegram chat, or their own address with Gmail's `dmarc=pass`); never a teammate, a stranger, Google Chat, the MCP server or an unattended run. *What may become memory*: episodic extraction runs only then, and only on the words outside `<untrusted_content>` blocks; peer memory and open loops are recorded under the speaker's own name, never as the principal's. *What may trigger tools*: every write on the principal's authority already refuses others in its handler; the tools with no such check that change the install for every later turn — `content_trust.PRINCIPAL_ONLY_TOOLS`, today `load_mcp_server` — are not offered unless the principal is speaking on an interactive surface (not email, even authenticated), and a call the model emits anyway gets an error tool_result and a `refused: not_principal` audit row. So an inbound email, a teammate's turn, Google Chat and the scheduler's proactive trigger each get a stable tool list of their own without it. *How it is labelled*: outside text goes into the user turn inside `<untrusted_content source=… author=… author_verified=…>` with a fixed notice that it carries no authority; compatibility forms are folded (NFKC), control characters go, and the tag's name is renamed wherever the text carries it — any case, spacing or entity-escaped form — so the text cannot end its block and speak outside it.\n\nA turn about the principal's private mail (`Session.private_to_principal`) reaches the principal only. It is neither offered nor allowed to run `schedule_tools.PRIVATE_TURN_WITHHELD_TOOLS` — everything that reaches someone else, publishes where the team reads, or starts work outside the turn: the broadcasts, meeting bookings and cancellations, `run_workflow` and research, follow-ups and workflow nudges, watches, artifacts, goal updates, saved workflows, skill drafts, and `load_mcp_server` (it connects to any URL, which can carry the turn's content). Through `search_tools` and `call_tool` it reaches only `schedule_tools.PRIVATE_TURN_MCP_TOOLS`: Google Workspace reads and the Gmail send and draft the gateway narrows to the principal. A search shows it nothing else, and a call to anything else (Google Chat, a Docs or Drive write, `manage_event`, another server) is refused (`schedule_tools.private_turn_withholds`). A call the model emits anyway, MCP tools included, gets an error tool_result and writes an audit row, and every audit row the turn writes is the principal's alone. On every turn the Executive knows what is connected without searching: block 0's *Connected Systems* section names the connected Google services, other MCP servers, the messaging channels, Notion sync and Act as me, and pins the Google tool names it calls directly with `call_tool`. `search_tools` is for anything not listed. Multiple parallel `tool_use` blocks in a single assistant turn fan out concurrently through `router.route_parallel`, each running its own domain-filtered ChromaDB query before the specialist sees the question. The fan-out is failure-isolated per call: a specialist that raises or returns no text becomes an `UNAVAILABLE` tool_result (`router.specialist_unavailable_result`) instead of failing the whole turn, and its area — \"finance\", \"legal\", never the specialist's name — is reported to the user under the web reply, or by the Executive in its reply on other channels, unless another call to it answered that turn. A failed specialist does not count as consulted, so it takes no committee seat. Cancellation (Stop) still propagates. The Executive then synthesizes the returned analyses into one reply.\n\n`remember_fact`, `forget_fact` and `update_company_profile` (`orchestrator/fact_tools.py`) make a correction stick: the first two keep or retire a standing fact in `memory.facts`, and the third changes one field of the company profile. They share `record_decision_outcome`'s gate (the principal on a verified surface, an audited refusal for everyone else) and are in `UNATTENDED_WITHHELD_TOOLS`. `remember_fact` alone also admits a rostered teammate on a verified surface (web signed in, their own Slack or Discord): the fact is stored attributed (`recorded_by_role=\"teammate\"`, rendered `(per <name>)`), and is held as a `proposed` row (`awaiting_approval`) until the principal approves it, unless the principal marked that teammate trusted (\"needs my approval\" off; on by default) — and even then when it would replace the principal's fact. All three are also in `PRIVATE_TURN_WITHHELD_TOOLS`, since what they write or retire is read on everyone's turns. On the principal's own authenticated email (primary address, with Gmail's own `Authentication-Results` reporting `dmarc=pass`, not forwarded) the three tools check the request as usual, then hold it as `awaiting_confirmation`. It applies only when the principal replies to a one-time token emailed to their own address (`integrations.fact_confirmation`); the split into a check step and an `apply_*` step lets chat and the confirmed reply share one apply path. Each write also needs a `source_quote` found in the speaker's own words this turn. The active facts reach every specialist as a `<standing_facts>` user-turn tag: `route_to_specialist` reads them (None → the store, \"\" → none) for chat consults and workflow steps alike, and `BaseAgent.analyze` places the tag next to `<past_decisions>`, never in the cached specialist system prompt.\n\nThe ten entries in `SPECIALIST_REGISTRY` (`openexecutive.orchestrator.router`):\n\n| Key | Agent | Domain |\n| --- | --- | --- |\n| `cso` | `StrategyAgent` | strategy |\n| `cfo` | `FinanceAgent` | finance |\n| `chro` | `HRAgent` | hr |\n| `gc` | `LegalAgent` | legal |\n| `coo` | `OperationsAgent` | operations |\n| `cmo` | `MarketingAgent` | marketing |\n| `cpo` | `ProductAgent` | product |\n| `sales` | `SalesAgent` | sales |\n| `board_comms` | `BoardCommsAgent` | board |\n| `triage` | `TriageAgent` | triage |\n\nModels: specialists default to `claude-sonnet-5`; a deep-reasoning tier uses `claude-opus-5` (adaptive thinking); routing/fast classification uses `claude-haiku-4-5`. The Council's **Deep reasoning** toggle is honoured on Claude Opus/Sonnet (direct or via OpenRouter) and on any OpenRouter model whose live catalog entry supports `reasoning` (today all OpenAI, Gemini, DeepSeek and Grok entries; not Llama) — the request translator turns Anthropic adaptive thinking + effort into OpenRouter's `reasoning` parameter. It is a silent no-op on models that can't reason, and disabled for Haiku, which rejects adaptive thinking. A PDF `document` block is translated too: it becomes an OpenAI `file` part, and OpenRouter requests carrying one add the `file-parser` plugin (`native` for models whose catalog entry lists `file` input, else `PDF_OPENROUTER_ENGINE`, default `mistral-ocr`). `FeatureSpec.supports_pdf_input` gates it per model — off for a local server unless `LOCAL_PDF_INPUT` — and a gated-off PDF becomes a text note rather than vanishing. The Council picks a model in two steps: a **Provider** dropdown (Anthropic, OpenAI, Google, Meta, DeepSeek, xAI, Local, …), then a **Model** dropdown limited to that provider, with readable names (\"Claude Opus 5.5\") and the raw id and serving route shown underneath. The Anthropic group combines the direct Claude models (`claude-fable-5-1`, `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5`, `claude-haiku-4-5`) with any Claude generation that exists only on OpenRouter, and never lists a model twice. With `OPENROUTER_ENABLED`, the non-Anthropic entries come from OpenRouter's live `/models` catalog (fetched at startup, refreshed in the background, filtered to tool-capable paid text models from an allowlisted vendor set), falling back to a built-in snapshot if the fetch fails. Every Council agent also takes **additional instructions** (`agent_overrides.instructions`): text appended after its prompt by `agents.overrides.append_instructions` inside an `<additional_instructions>` block. `BaseAgent.base_system_prompt()` is the built-in prompt or its full replacement (what the Council's editor shows); `effective_system_prompt()` is that plus the instructions (what every call sends), and the Executive gets the same text through `build_system_blocks(persona_instructions=…)`. Unlike a replaced prompt, instructions leave the agent on its built-in prompt, so prompt improvements keep reaching it. A **Quality** choice above the agents (`agents.presets`) sets every agent's model and deep reasoning at once: **Fast** puts every agent on a small model (`claude-haiku-4-5`) with deep reasoning off, **Balanced** returns each agent to its built-in defaults, and **Thorough** puts the Executive and the domain specialists on the largest allowed model (`claude-opus-5-5`, else `claude-opus-5`) with deep reasoning on where the model supports it, leaving triage and the helpers below on their defaults. Presets change quality only; they never cap spend. Each preset resolves against the install's model allowlist at request time and is offered only when one of its models is allowed. Applying one writes ordinary per-agent overrides (model and deep reasoning only), so history, rollback and later per-agent edits keep working; an agent changed on its own afterwards shows as **Custom**. Eight Council-only agents are model/prompt-overridable in the UI but NOT callable via `consult_specialist`, because they are deliberately kept out of `SPECIALIST_REGISTRY`: `quality_judge` (committee review), `utility_fast` (gates, titles, decision parsing), `research` (the `executive_research` fan-out), `fixture_generator` (invents demo companies), `engagement_intake` (models a real client from intake material), `onboarding_interviewer` (interviews a new user about their own company and drafts its profile, people and departments), `workflow_designer` (runs the conversational New workflow wizard on `/jobs/new`: searches the available tools, asks clarifying questions, then drafts a validated dynamic-workflow definition for the user to review), and `workflow_actor` (runs a workflow's `action` steps: a bounded tool-use loop limited to the tools the user approved for that step). `fixture_generator`, `engagement_intake` and `onboarding_interviewer` share one shape — a forced tool call producing a whole company, validated for referential integrity, with a single repair retry — but opposite epistemics: the fixture author invents, the other two extract and leave unstated facts empty rather than guessing. When the workspace is in solo mode, `onboarding_interviewer`'s first user turn is prefixed with a short hint (`interview.solo_hint(role_kind)`, one static constant per role kind from the onboarding role step): the draft names only the principal, as principal, and no departments; an owner is asked about the offer, customers, pricing, cash and runway, an in-house executive about their organisation (drafted as the company — their employer), function, remit, manager, team size as context and what they are measured on, an independent about their practice, clients and pricing, and with no role given the role-neutral `SOLO_HINT` asks which they are. The hint rides in the user turn and the tool array is unchanged, so the cached system prompt and tool prefix are the same in both modes.\n\n**Voice.** The Executive answers in one voice persona, substituted into block 0 at `{VOICE_PERSONA}` (`personas/loader.get_active_body`) from the Executive override's `voice_persona_slug`. Three general voices ship in `personas/builtin/`: **Direct** (`default`, the slug used when none is set: answer first, brief and decisive), **Supportive** (a warm coach who explains the why and checks how the plan sits) and **Analytical** (numbers first, options and trade-offs, then one recommendation). They are offered by a shared picker in setup (`/onboard`, after the workspace choice) and in Settings → Executive, which saves through `PATCH /agents/executive`; a built-in voice's frontmatter carries the picker's one-line `description` and `sample` reply. The named-executive voices are marked `legacy: true`: the picker hides them, but they still load, so an install that picked one keeps it, and the Agent Council lists them under \"Legacy voices\". Voice files hold disposition only; the response-length ladder lives in `prompts/executive_persona.py`, and a test keeps numeric length rules out of every voice file. An eval scenario may set `voice_persona` to answer in a voice; it rides on `Session.voice_persona_slug`, which wins over the override for that session only.\n\nOne more structured-output utility agent sits beside `triage`: `openexecutive.agents.alert_review.AlertReviewAgent` (routing model, one forced `emit_alert_reviews` tool call, never raises). The alert review job hands it a batch of open alerts with evidence and gets back, per alert, a verdict (relevant / changed / resolved / stale), a confidence, the evidence it relied on, a one-line note, why-now, an optional deadline, and a recommended move (none / route / nudge / escalate / draft / suggest_workflow / merge / close) with its parameters. Like `triage`, it never mutates state — `alerts.review.apply_verdict` executes the verdicts deterministically within authority, so the model's job is judgment, not action.\n\n**Solo mode.** When the workspace (or the turn's session) is solo — one person using Open Executive for themselves — the Executive works for that one person, the principal, whatever their role: they may run their own business, lead a function inside a larger organisation, or work independently, and the persona reads which from the context instead of assuming it — the role lines under \"Your Principal\" in the org block, when the principal gave their role (workspace settings: kind, title, reports to, remit, measured on). Its persona swaps the team sections (\"You Are a Member of This Executive Team\", \"Choosing Who to Tell\", \"Departments & Org Coordination\") for \"You Work for One Person\", \"The People in Their World\", \"Who Hears From You\" and \"Goals and Areas\". Solo means only the principal uses Open Executive — not that they have no people: their manager, direct reports, peers, clients, investors and board are contacts. The Executive helps the principal work with them (a 1:1 or review prep, an update or budget case for their manager or board, a negotiation) but does not coordinate them, contacts them only when the principal asks and only if they are a contact, and never offers to loop the principal in. Every specialist stays relevant — HR for the principal's own reports, board and investor communications for reporting upward. Goals are grouped by *area* (the tools' `department_slug` is the area's slug). The chat loop withholds `send_department_message`, `send_company_broadcast` and `set_department_head` from its tool list, and a call to one of them anyway gets a JSON error tool_result instead of running. The mode is resolved once per turn and pinned on the session, so the persona, the org block, the tools and every tool handler agree — a switch made mid-turn applies from the next turn. Team mode is unchanged.\n\nEvery specialist *advises* — each returns domain analysis the Executive synthesizes into one voice. None of them act on the company's behalf; the side-effecting tools in the main loop (schedule, people, departments, broadcast, watchlist, workflows) belong to the Executive, not to a specialist.\n\nOne tool writes under someone else's name, and it is fenced in code rather than the prompt. `ghostwrite_email` (**Act as me**, `orchestrator.delegation_tools`) writes an email as the person the Executive is speaking with and saves it as a draft in their own Gmail; it never sends. It lives in its own registry, never `_ALL_SKILL_TOOLS`, so reflection, research and workflow toolkits can never carry it. The chat loop adds it only on a turn `delegation.settings.pin_turn_delegation` offered it to — the principal, with it on, verified, in a conversation private to them (the web chat, a Slack or Discord DM, a verified private Telegram chat), on an attended turn — and builds that turn's handler map from both registries, so on any other turn a call to it is an unknown tool. Recipients are chosen in code, never by the model, and the text comes from the **ghostwriter** (`delegation.ghostwriter`), a tool-less call with a constant prompt plus the person's \"How I write\" profile. The ghostwriter is deliberately not a Council agent: the Council's edit routes have no principal check. See **Act as Me (Delegation)**.\n\nThe Executive can also launch *any* workflow conversationally: `orchestrator.workflow_run_tools` adds `list_workflows` (the launchable catalog with each workflow's inputs) and `run_workflow` (runs a built-in or custom workflow to completion and returns its artifact, checkpointing approval gates as `awaiting_human`). `run_workflow` runs the weekly review, and in solo mode the morning brief, only for the principal on a verified surface (`Workflow.principal_only_modes`, `create_goal`'s rule); anyone else gets an audited refusal that does not name the rule. A run whose `result` event reports `private_to_principal` (the morning brief on the principal's own verified turn, when it read their private rows) still returns its artifact into that turn, but the stored run keeps `persistence.PRIVATE_RUN_ARTIFACT` instead of the text, since run history is readable by everyone signed in. This makes the `/jobs` catalog reachable from chat — see the Workflows section.\n\nDeliverables are first-class too. `orchestrator.artifact_tools` gives the Executive three tools: `draft_artifact` publishes a memo, web page (`html`), Word document (`docx`), spreadsheet (`xlsx`, from structured `sheets`) or a `link` to something it created in one of the principal's connected apps through the generic MCP gateway (`search_tools` → `call_tool`, any server — no vendor is named), and returns the artifact's id and link; `list_artifacts` and `get_artifact` let it find and reread its own past work (drafts and workflow outputs alike, through the same `artifact_records` read model the API uses). Revising is `draft_artifact(supersedes=<id>)`, which archives the earlier version. When the principal asks for a deliverable the tool is always used; the \"quiet is the right default\" bar applies only to unprompted drafts. The format enum is a hard-coded sorted tuple so the cached tool schema stays byte-stable. Delivery: `message_person(person_id, text, artifact_id?)` appends the artifact's title and a `UI_BASE_URL/artifacts/<id>` link (through the same outbound guard as any DM; the link needs Open Executive access), and a Gmail send/draft can attach the file itself by `artifact_id` — see Integrations.\n\nDocuments come in the other way through `read_document` (`orchestrator.document_tools`): it reads a PDF, Word, Excel, CSV, Markdown or text file by `path` — one another tool saved, such as a Gmail attachment (`get_gmail_attachment_content`) or a Drive file (`get_drive_file_download_url`) — or a company document by `filename`, with an optional PDF `pages` range. A scanned PDF is converted (`knowledge.pdf_reader`: local OCR by default; with `PDF_PROVIDER_READING=true`, the deployment's own model through its provider's PDF support, falling back to local OCR) rather than returned empty. Reads are confined to the tool download folders — the same resolve-then-contain check as `oe__read_file` — plus the company docs folder, and it is withheld on turns private to the principal (`PRIVATE_TURN_WITHHELD_TOOLS`): those come from a contact's email, whose own attachments the poller has already read into the turn, and must not steer the Executive into company documents.\n\nThe Executive also backs the **Ask OE** panel's form-fill tier via `orchestrator.form_tools.propose_form_values`: when a chat turn arrives with a `<page_context>` block describing a form on the user's screen, the Executive can propose values for it. The proposal is delivered to the UI as a `form_patch` SSE event and placed into the form as highlighted suggestions — the tool never saves or submits anything; the user reviews and saves manually. The tool is **always** in the tool list (tool definitions sit at the top of the cached prompt prefix, so a conditionally-present tool would invalidate the prompt cache whenever panel and non-panel turns alternate); its description restricts usage to turns that carry a form descriptor.","mermaid": "flowchart TD\n User([User message]) --> Exec[\"Executive<br/>orchestrator\"]\n Exec -->|consult_specialist| Cso[\"cso: StrategyAgent\"]\n Exec -->|consult_specialist| Cfo[\"cfo: FinanceAgent\"]\n Exec -->|consult_specialist| Gc[\"gc: LegalAgent\"]\n Exec -->|consult_specialist| More[\"chro / coo / cmo / cpo / sales<br/>board_comms / triage\"]\n Mode{{\"Team or solo<br/>(persona + tools per turn)\"}} --> Exec\n Exec -->|\"ghostwrite_email (Act as me)\"| Gw[\"ghostwriter<br/>(tool-less, not a Council agent)\"]\n Cso --> Claude[\"Claude (Anthropic)\"]\n Cfo --> Claude\n Gc --> Claude\n More --> Claude\n Claude --> Exec\n class User entry\n class Exec compute\n class Mode compute\n class Cso compute\n class Cfo compute\n class Gc compute\n class More compute\n class Claude external\n class Gw compute",- "generated_at": "2026-10-01T16:28:49Z"+ "generated_at": "2026-10-01T16:39:33Z"}diff --git a/packages/core/openexecutive/evals/_scenarios/voice_analytical_001.yaml b/packages/core/openexecutive/evals/_scenarios/voice_analytical_001.yamlnew file mode 100644index 00000000..6ae0cae7--- /dev/null+++ b/packages/core/openexecutive/evals/_scenarios/voice_analytical_001.yaml@@ -0,0 +1,27 @@+id: voice_analytical_001+domain: voice+voice_persona: analytical+description: "Analytical voice: a founder asks whether to raise prices or spend more on acquisition. The Executive leads with the numbers that decide it, lays out the two options with their trade-offs and assumptions, and still lands on one recommendation."+# Runs in the Analytical voice via the `voice_persona` key+# (Session.voice_persona_slug), never the install-wide Executive override.+company_context:+ name: Fernway Software+ industry: Vertical SaaS for Veterinary Clinics+ stage: Series A+ headcount: 42+ arr: 4800000+ monthly_burn: 380000+ runway_months: 19+query: "We have about $400k to put toward growth this year. Should we raise prices 15% on new customers or spend it on paid acquisition? Our CAC is around $3,200, average contract is $9,000 a year, and gross margin is 78%."+expected_topics:+ - payback_or_ltv_to_cac_from_the_given_figures+ - price_increase_option_with_its_trade_off+ - paid_acquisition_option_with_its_trade_off+ - stated_assumptions+ - single_recommendation+quality_criteria:+ uses_the_figures_given: true+ compares_both_options_on_cost_gain_and_risk: true+ states_the_assumptions_behind_the_conclusion: true+ ends_with_one_recommendation: true+ not_generic: truediff --git a/packages/core/openexecutive/evals/_scenarios/voice_supportive_001.yaml b/packages/core/openexecutive/evals/_scenarios/voice_supportive_001.yamlnew file mode 100644index 00000000..aaac4a8f--- /dev/null+++ b/packages/core/openexecutive/evals/_scenarios/voice_supportive_001.yaml@@ -0,0 +1,24 @@+id: voice_supportive_001+domain: voice+voice_persona: supportive+description: "Supportive voice: a first-time manager asks whether to let go of an underperforming early hire. The Executive still gives a clear recommendation, explains why, acknowledges that the call is hard, helps with how to deliver it, and stays inside the persona's length rules (warmth must not turn into padding)."+# Runs in the Supportive voice via the `voice_persona` key+# (Session.voice_persona_slug), never the install-wide Executive override.+company_context:+ name: Brightline Analytics+ industry: B2B Data Tooling+ stage: Seed+ headcount: 9+ arr: 600000+query: "One of our first five hires keeps missing deadlines and the rest of the team is picking up the slack. I've given feedback twice. I hate this, but should I let them go?"+expected_topics:+ - clear_recommendation+ - why_the_recommendation_holds+ - acknowledges_the_difficulty+ - how_to_handle_the_conversation+quality_criteria:+ gives_a_clear_recommendation_up_front: true+ explains_the_reasoning_in_plain_language: true+ warm_without_flattery_or_padding: true+ addresses_how_the_decision_lands_on_people: true+ brief: truediff --git a/packages/core/openexecutive/evals/runner.py b/packages/core/openexecutive/evals/runner.pyindex c3b6a7f5..66ff3648 100644--- a/packages/core/openexecutive/evals/runner.py+++ b/packages/core/openexecutive/evals/runner.py@@ -29,6 +29,10 @@ settings' role fields) to play a principal with that role. It goes on thesession (``Session.principal_role``) the same way, never into theinstall-wide settings row, which concurrent scenarios would share.+A chat scenario may set ``voice_persona`` (a voice slug such as+``supportive``) to answer in that voice. It goes on+``Session.voice_persona_slug``, never the Executive's install-wide override.+A chat scenario may set a ``delegation`` block (Act as me: the asker, theirthreads) to run with ``ghostwrite_email`` offered against an in-memorymailbox (``scenarios.scenario_delegation``); the drafts it saves go to the@@ -49,6 +53,7 @@ from openexecutive.evals.scenarios import (load_scenarios,scenario_delegation,scenario_principal_role,+ scenario_voice_persona,)from openexecutive.workflows.gate import ensure_workflow_event@@ -408,6 +413,7 @@ def _make_chat_runner(company_profile=profile,workspace_mode=scenario_workspace_mode(scenario),principal_role=scenario_principal_role(scenario),+ voice_persona_slug=scenario_voice_persona(scenario),delegation_override=delegation,)query = scenario["query"]diff --git a/packages/core/openexecutive/evals/scenarios.py b/packages/core/openexecutive/evals/scenarios.pyindex b0593217..eede3360 100644--- a/packages/core/openexecutive/evals/scenarios.py+++ b/packages/core/openexecutive/evals/scenarios.py@@ -134,6 +134,20 @@ def scenario_principal_role(scenario: dict[str, Any]) -> PrincipalRole | None:return role+def scenario_voice_persona(scenario: dict[str, Any]) -> str | None:+ """The scenario's ``voice_persona`` slug, or None to use the install's+ voice. An unknown slug raises ValueError, so a typo fails the scenario+ instead of silently running in the default voice."""+ from openexecutive.personas.loader import persona_exists++ slug = scenario.get("voice_persona")+ if slug is None:+ return None+ if not isinstance(slug, str) or not persona_exists(slug):+ raise ValueError(f"voice_persona {slug!r} is not a known voice")+ return slug++def scenario_delegation(scenario: dict[str, Any]) -> Any:"""The scenario's ``delegation`` block (Act as me) as a``delegation.settings.DelegationOverride`` over a fresh in-memory mailbox@@ -233,6 +247,8 @@ def validate_scenario_yaml(raw: str) -> dict[str, Any]:scenario_principal_role(s)except ValueError as e:raise ValueError(f"`principal_role`: {e}") from e+ if s.get("voice_persona") is not None:+ scenario_voice_persona(s)if s.get("delegation") is not None:try:scenario_delegation(s)diff --git a/packages/core/openexecutive/orchestrator/executive.py b/packages/core/openexecutive/orchestrator/executive.pyindex 3444ff09..61f6f4f3 100644--- a/packages/core/openexecutive/orchestrator/executive.py+++ b/packages/core/openexecutive/orchestrator/executive.py@@ -851,7 +851,10 @@ class Executive:persona_instructions = _ov.instructionsif _ov is not None and _ov.model:effective_model = _ov.model- voice_persona_body = _get_voice_body(_ov.voice_persona_slug if _ov else None)+ voice_persona_body = _get_voice_body(+ session.voice_persona_slug+ or (_ov.voice_persona_slug if _ov else None)+ )except Exception:logger.exception("Failed to load executive override; using defaults")# Solo / team, resolved once per turn and pinned on the session, so the@@ -1165,7 +1168,10 @@ class Executive:persona_instructions = _ov.instructionsif _ov is not None and _ov.model:effective_model = _ov.model- voice_persona_body = _get_voice_body(_ov.voice_persona_slug if _ov else None)+ voice_persona_body = _get_voice_body(+ session.voice_persona_slug+ or (_ov.voice_persona_slug if _ov else None)+ )except Exception:logger.exception("Failed to load executive override; using defaults")diff --git a/packages/core/openexecutive/orchestrator/session.py b/packages/core/openexecutive/orchestrator/session.pyindex ea9c0580..f16a64e5 100644--- a/packages/core/openexecutive/orchestrator/session.py+++ b/packages/core/openexecutive/orchestrator/session.py@@ -85,6 +85,10 @@ class Session:# of the principal it plays without writing the install-wide row. Read# it through `memory.workspace_settings.effective_principal_role`.principal_role: PrincipalRole | None = None+ # Per-session voice persona slug (None = the Executive override's voice,+ # else Direct), so an eval scenario can play a voice without writing the+ # install-wide override that concurrent scenarios share.+ voice_persona_slug: str | None = None# The mode resolved for the turn in progress, pinned at its start by# `workspace_settings.pin_turn_workspace_mode` (Executive.stream_chat and# the committee path) so the tool handlers use the same mode as thediff --git a/packages/core/openexecutive/personas/builtin/analytical.md b/packages/core/openexecutive/personas/builtin/analytical.mdnew file mode 100644index 00000000..aacfba8a--- /dev/null+++ b/packages/core/openexecutive/personas/builtin/analytical.md@@ -0,0 +1,21 @@+---+slug: analytical+display_name: Analytical+description: Numbers first. Lays out the options and the trade-offs between them before recommending one.+sample: |+ Two options. Hire now: about $90k for the next six months, and the two slipped releases ship a quarter earlier. Wait a quarter: you save the $90k, but at your current churn that delay risks roughly $120k of renewals. Hiring now comes out ahead unless your runway is under nine months.+source_notes: |+ Built-in Open Executive voice: a quantitative, options-and-trade-offs operator.+ Voice/disposition only. Concrete response-length and formatting rules live in+ the Length and Format sections of prompts/executive_persona.py; keep numeric+ ceilings out of this file so the two cannot drift apart.+---+Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.++- **Numbers first.** You anchor every answer in the figures that drive it: cost, revenue, margin, runway, conversion, time. When the numbers are missing, you say which ones you need and make a clearly labelled estimate rather than reasoning in adjectives.+- **Options and trade-offs.** For a real decision you set out the credible options side by side, with what each one costs, what it gains and what it risks, then say which you would pick and the condition under which you would pick differently. A simple question gets a simple answer, not a menu.+- **Explicit assumptions.** You state the assumptions your conclusion rests on, so the person can see which one would change it.+- **Precise language.** You prefer specific quantities and ranges to vague words like "significant" or "a lot". You separate facts, estimates and guesses.+- **Structured, not academic.** You think in frameworks (unit economics, expected value, sensitivity) but you show the result, not the method, unless the person asks for the working.+- **Sceptical of single data points.** You flag small samples, survivorship and correlation passing as cause, and you suggest the cheapest way to get a better number.+- **Decisive at the end.** The analysis always lands on a recommendation. You never leave the person holding a table with no answer.diff --git a/packages/core/openexecutive/personas/builtin/andy-jassy.md b/packages/core/openexecutive/personas/builtin/andy-jassy.mdindex b0a07427..fbcb8da1 100644--- a/packages/core/openexecutive/personas/builtin/andy-jassy.md+++ b/packages/core/openexecutive/personas/builtin/andy-jassy.md@@ -1,6 +1,7 @@---slug: andy-jassydisplay_name: Andy Jassy (Amazon)+legacy: truesource_notes: Amazon shareholder letters 2021–2025, AWS re:Invent keynotes, earnings call commentary, Working Backwards (Bryar & Carr, 2021) as framework reference.---Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.diff --git a/packages/core/openexecutive/personas/builtin/brian-chesky.md b/packages/core/openexecutive/personas/builtin/brian-chesky.mdindex a5e97795..45e6ee6a 100644--- a/packages/core/openexecutive/personas/builtin/brian-chesky.md+++ b/packages/core/openexecutive/personas/builtin/brian-chesky.md@@ -1,6 +1,7 @@---slug: brian-cheskydisplay_name: Brian Chesky (Airbnb)+legacy: truesource_notes: Airbnb shareholder letters 2021–2025, Masters of Scale podcast, Lenny's Podcast 2023, Lex Fridman podcast 2024, public commentary on CEO involvement and product philosophy.---Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.diff --git a/packages/core/openexecutive/personas/builtin/dario-amodei.md b/packages/core/openexecutive/personas/builtin/dario-amodei.mdindex 2fcd2c6d..ad5fb779 100644--- a/packages/core/openexecutive/personas/builtin/dario-amodei.md+++ b/packages/core/openexecutive/personas/builtin/dario-amodei.md@@ -1,6 +1,7 @@---slug: dario-amodeidisplay_name: Dario Amodei (Anthropic)+legacy: truesource_notes: '"Machines of Loving Grace" essay (2024), Lex Fridman podcast 2024, Dwarkesh Patel podcast 2023 and 2024, Anthropic blog posts on safety and scaling, public talks at universities and conferences.'---Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.diff --git a/packages/core/openexecutive/personas/builtin/default.md b/packages/core/openexecutive/personas/builtin/default.mdindex d2000be5..ebcb560c 100644--- a/packages/core/openexecutive/personas/builtin/default.md+++ b/packages/core/openexecutive/personas/builtin/default.md@@ -1,6 +1,9 @@---slug: default-display_name: Default Executive+display_name: Direct+description: Answer first, brief and decisive. Gives a clear recommendation and the one reason behind it.+sample: |+ Hire the second engineer now. Your backlog is already slipping two releases, and the cost of one more quarter of delay is higher than six months of salary.source_notes: |Built-in Open Executive voice — direct, data-grounded, outcome-focused operator.Voice/disposition only. Concrete response-length and formatting rules live indiff --git a/packages/core/openexecutive/personas/builtin/jensen-huang.md b/packages/core/openexecutive/personas/builtin/jensen-huang.mdindex d02ef13c..49b1d916 100644--- a/packages/core/openexecutive/personas/builtin/jensen-huang.md+++ b/packages/core/openexecutive/personas/builtin/jensen-huang.md@@ -1,6 +1,7 @@---slug: jensen-huangdisplay_name: Jensen Huang (NVIDIA)+legacy: truesource_notes: GTC keynotes 2023–2026, NVIDIA shareholder letters, Stanford GSB talk 2023, Lex Fridman podcast 2023.---Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.diff --git a/packages/core/openexecutive/personas/builtin/mark-zuckerberg.md b/packages/core/openexecutive/personas/builtin/mark-zuckerberg.mdindex 3188252a..d124e9c6 100644--- a/packages/core/openexecutive/personas/builtin/mark-zuckerberg.md+++ b/packages/core/openexecutive/personas/builtin/mark-zuckerberg.md@@ -1,6 +1,7 @@---slug: mark-zuckerbergdisplay_name: Mark Zuckerberg (Meta)+legacy: truesource_notes: Meta earnings calls 2021–2025, Lex Fridman podcast 2021 and 2023, founder letters, Threads and Instagram Live appearances, Joe Rogan podcast 2025.---Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.diff --git a/packages/core/openexecutive/personas/builtin/patrick-collison.md b/packages/core/openexecutive/personas/builtin/patrick-collison.mdindex c3223c30..ddc8b285 100644--- a/packages/core/openexecutive/personas/builtin/patrick-collison.md+++ b/packages/core/openexecutive/personas/builtin/patrick-collison.md@@ -1,6 +1,7 @@---slug: patrick-collisondisplay_name: Patrick Collison (Stripe)+legacy: truesource_notes: Stripe blog posts, Invest Like the Best and Founders podcast appearances, Patrick's personal site essays, Stripe annual letters, conversations on science and progress.---Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.diff --git a/packages/core/openexecutive/personas/builtin/satya-nadella.md b/packages/core/openexecutive/personas/builtin/satya-nadella.mdindex 6888e840..40331b7b 100644--- a/packages/core/openexecutive/personas/builtin/satya-nadella.md+++ b/packages/core/openexecutive/personas/builtin/satya-nadella.md@@ -1,6 +1,7 @@---slug: satya-nadelladisplay_name: Satya Nadella (Microsoft)+legacy: truesource_notes: '"Hit Refresh" (2017), Microsoft shareholder letters 2014-2025, Build keynotes, Davos interviews, podcasts with Patrick O''Shaughnessy and others.'---Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.diff --git a/packages/core/openexecutive/personas/builtin/sundar-pichai.md b/packages/core/openexecutive/personas/builtin/sundar-pichai.mdindex 2d4974b3..a8021b78 100644--- a/packages/core/openexecutive/personas/builtin/sundar-pichai.md+++ b/packages/core/openexecutive/personas/builtin/sundar-pichai.md@@ -1,6 +1,7 @@---slug: sundar-pichaidisplay_name: Sundar Pichai (Google/Alphabet)+legacy: truesource_notes: Google I/O keynotes 2015–2025, Alphabet shareholder letters, Recode Decode and Lex Fridman interviews, Code Conference appearances.---Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.diff --git a/packages/core/openexecutive/personas/builtin/supportive.md b/packages/core/openexecutive/personas/builtin/supportive.mdnew file mode 100644index 00000000..cd4e898a--- /dev/null+++ b/packages/core/openexecutive/personas/builtin/supportive.md@@ -0,0 +1,21 @@+---+slug: supportive+display_name: Supportive+description: A warm coach. Explains the why behind each recommendation and checks how the plan sits with you.+sample: |+ I'd hire the second engineer now. The backlog is slipping, and every release that waits costs you more than the salary would. I know a hire feels like a big commitment at this stage, so if cash is the worry, let's look at what a six-month contract would do first.+source_notes: |+ Built-in Open Executive voice: a warm, coaching operator.+ Voice/disposition only. Concrete response-length and formatting rules live in+ the Length and Format sections of prompts/executive_persona.py; keep numeric+ ceilings out of this file so the two cannot drift apart.+---+Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.++- **Warm and on their side.** You speak like a trusted coach who wants the person to succeed. You acknowledge what is hard about their situation in a few words, then move to what to do about it. Warmth never replaces a recommendation.+- **Explains the why.** You still lead with what you would do, then give the reasoning in plain language so the person can apply it to the next decision on their own. You teach the principle, not just the answer.+- **Builds confidence without flattery.** You name what the person is already doing well when it is true and relevant, and you never praise to soften bad news. When the plan has a real problem, you say so kindly and clearly.+- **Checks in on fit.** When a recommendation depends on something only the person knows (their appetite for risk, their team's capacity, how they feel about a hard conversation), you name it and invite them to weigh in rather than assuming.+- **People-aware.** You notice how a decision lands on the people involved: the team, a co-founder, a customer. You suggest how to communicate a hard call, not only whether to make it.+- **Honest about uncertainty.** You distinguish what you know from what you are guessing, and you surface risks gently but without hiding them.+- **Calm and steady.** Under pressure you slow things down, break the problem into the next step, and keep the tone reassuring. You never lecture.diff --git a/packages/core/openexecutive/personas/builtin/tim-cook.md b/packages/core/openexecutive/personas/builtin/tim-cook.mdindex cc971340..6d7ca09f 100644--- a/packages/core/openexecutive/personas/builtin/tim-cook.md+++ b/packages/core/openexecutive/personas/builtin/tim-cook.md@@ -1,6 +1,7 @@---slug: tim-cookdisplay_name: Tim Cook (Apple)+legacy: truesource_notes: Apple shareholder letters 2011–2025, AllThingsD/D Conference interviews, MIT commencement 2017, earnings calls, TIME and Fortune interviews.---Adopt the voice, tone, register, and communication style described below. Embody this persona's mannerisms and signature emphases while keeping all other guidance in this prompt fully in force.diff --git a/packages/core/openexecutive/personas/loader.py b/packages/core/openexecutive/personas/loader.pyindex 5ca84c81..0f0299d9 100644--- a/packages/core/openexecutive/personas/loader.py+++ b/packages/core/openexecutive/personas/loader.py@@ -7,7 +7,15 @@ DB row restores the built-in. Pure-custom slugs (no built-in) are fully deletedwhen their DB row is removed.Active persona selection is stored on the agent_overrides row for "executive"-as voice_persona_slug. NULL resolves to "default".+as voice_persona_slug. NULL resolves to "default" (shown as "Direct").++Three built-in voices are offered in the voice picker: Direct (``default``),+Supportive and Analytical. The named-executive voices carry ``legacy: true``+in their frontmatter: the picker hides them, but they still load, so an+install that picked one keeps its voice. A built-in voice's frontmatter may+also carry a one-line ``description`` and a short ``sample`` reply for the+picker. Voice files hold disposition only; response-length rules live in+``prompts/executive_persona.py``."""from __future__ import annotations@@ -33,6 +41,11 @@ class PersonaMeta(BaseModel):display_name: stris_builtin: boolis_customized: bool+ # Hidden from the voice picker but still loadable (built-in only).+ is_legacy: bool = False+ # Picker copy from the built-in's frontmatter ("" for custom voices).+ description: str = ""+ sample: str = ""class Persona(BaseModel):@@ -42,6 +55,9 @@ class Persona(BaseModel):is_builtin: boolis_customized: boolsource_notes: str = ""+ is_legacy: bool = False+ description: str = ""+ sample: str = ""def _parse_md(path: Path) -> dict[str, Any]:@@ -68,6 +84,9 @@ def _load_builtins() -> dict[str, Persona]:is_builtin=True,is_customized=False,source_notes=data.get("source_notes", ""),+ is_legacy=bool(data.get("legacy", False)),+ description=str(data.get("description", "")).strip(),+ sample=str(data.get("sample", "")).strip(),)return out@@ -120,6 +139,9 @@ def list_personas(db_path: Path | None = None) -> list[PersonaMeta]:display_name=db_rows[slug]["display_name"] if slug in db_rows else builtin.display_name,is_builtin=True,is_customized=slug in db_rows,+ is_legacy=builtin.is_legacy,+ description=builtin.description,+ sample=builtin.sample,))for slug, row in db_rows.items():@@ -152,6 +174,9 @@ def get_persona(slug: str, db_path: Path | None = None) -> Persona | None:is_builtin=slug in builtins,is_customized=True,source_notes=builtin.source_notes if builtin else "",+ is_legacy=builtin.is_legacy if builtin else False,+ description=builtin.description if builtin else "",+ sample=builtin.sample if builtin else "",)if slug in builtins:diff --git a/packages/core/tests/unit/test_voice_picker.py b/packages/core/tests/unit/test_voice_picker.pynew file mode 100644index 00000000..5ee6bd3f--- /dev/null+++ b/packages/core/tests/unit/test_voice_picker.py@@ -0,0 +1,131 @@+"""The three general voices (Direct, Supportive, Analytical), legacy named+voices, and playing a voice per session for evals."""+from __future__ import annotations++import asyncio+import re+from pathlib import Path+from typing import Any+from unittest.mock import patch++import pytest++from openexecutive.evals.scenarios import scenario_voice_persona, validate_scenario_yaml+from openexecutive.memory import episodic+from openexecutive.orchestrator.executive import Executive+from openexecutive.orchestrator.session import Session+from openexecutive.personas import loader+from openexecutive.personas.loader import (+ get_active_body,+ get_persona,+ invalidate_builtin_cache,+ list_personas,+)++GENERAL = ("default", "supportive", "analytical")+_BUILTIN_DIR = Path(loader.__file__).parent / "builtin"+# Numeric response-length ceilings belong in prompts/executive_persona.py.+_LENGTH_RULE_RE = re.compile(+ r"\b\d+\s*(?:words?|sentences?|paragraphs?|bullets?|lines?|characters?)\b"+ r"|\bunder\s+\d+\b|\bat most\s+\d+\b",+ re.IGNORECASE,+)++[email protected](autouse=True)+def _isolated(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ db = tmp_path / "voice.db"+ monkeypatch.setattr(episodic, "DB_PATH", db)+ monkeypatch.setattr(loader, "DB_PATH", db)+ invalidate_builtin_cache()+ return db+++def test_general_voices_load_with_picker_copy(_isolated: Path) -> None:+ metas = {m.slug: m for m in list_personas(db_path=_isolated)}+ assert {s: metas[s].display_name for s in GENERAL} == {+ "default": "Direct",+ "supportive": "Supportive",+ "analytical": "Analytical",+ }+ for slug in GENERAL:+ assert metas[slug].is_legacy is False+ assert metas[slug].description+ assert metas[slug].sample+ assert get_active_body(slug, db_path=_isolated)+++def test_named_voices_are_legacy_but_still_resolve(_isolated: Path) -> None:+ legacy = [m for m in list_personas(db_path=_isolated) if m.is_legacy]+ assert {m.slug for m in legacy} >= {"tim-cook", "satya-nadella", "jensen-huang"}+ assert not {m.slug for m in legacy} & set(GENERAL)+ body = get_active_body("tim-cook", db_path=_isolated)+ assert body and body != get_active_body(None, db_path=_isolated)+++def test_customized_builtin_keeps_its_picker_metadata(_isolated: Path) -> None:+ loader.upsert_persona("tim-cook", "Tim", "Custom body", db_path=_isolated)+ p = get_persona("tim-cook", db_path=_isolated)+ assert p is not None and p.is_legacy is True and p.body == "Custom body"+ loader.upsert_persona("supportive", "Kind", "Warm body", db_path=_isolated)+ meta = next(m for m in list_personas(db_path=_isolated) if m.slug == "supportive")+ assert meta.is_customized and meta.description and not meta.is_legacy++[email protected]("path", sorted(_BUILTIN_DIR.glob("*.md")), ids=lambda p: p.stem)+def test_voice_bodies_carry_no_length_rules(path: Path) -> None:+ body = loader._parse_md(path)["body"]+ hits = _LENGTH_RULE_RE.findall(body)+ assert not hits, f"{path.name} sets a length rule: {hits}"+++def test_scenario_voice_persona() -> None:+ assert scenario_voice_persona({}) is None+ assert scenario_voice_persona({"voice_persona": "supportive"}) == "supportive"+ with pytest.raises(ValueError):+ scenario_voice_persona({"voice_persona": "supportve"})+ with pytest.raises(ValueError):+ validate_scenario_yaml("id: x\nquery: hi\nvoice_persona: nope\n")+++def test_shipped_voice_scenarios_name_real_voices() -> None:+ scenarios = Path(loader.__file__).parents[1] / "evals" / "_scenarios"+ for name, slug in (("voice_supportive_001", "supportive"), ("voice_analytical_001", "analytical")):+ s = validate_scenario_yaml((scenarios / f"{name}.yaml").read_text())+ assert scenario_voice_persona(s) == slug+++def test_session_voice_wins_over_the_install_voice(_isolated: Path) -> None:+ """Evals play a voice on the session; the Executive override is untouched."""+ from openexecutive.agents import overrides as ov_mod++ monkey_db = _isolated+ with patch.object(ov_mod, "DB_PATH", monkey_db):+ ov_mod.invalidate_cache()+ ov_mod.set_override("executive", voice_persona_slug="analytical", voice_persona_slug_set=True)+ bodies: list[Any] = []++ def _blocks(*_a: Any, **kw: Any) -> list[dict[str, Any]]:+ bodies.append(kw.get("voice_persona_body"))+ return [{"type": "text", "text": "persona"}]++ async def _loop(*_a: Any, **_kw: Any): # type: ignore[no-untyped-def]+ yield "Hello."++ async def _drain(session: Session) -> None:+ async for _ in Executive().stream_chat(user_message="hi", session=session):+ pass++ with (+ patch("openexecutive.orchestrator.executive.build_system_blocks", new=_blocks),+ patch.object(Executive, "_stream_agent_loop", new=_loop),+ patch("openexecutive.orchestrator.executive.audit_log", lambda *a, **k: None),+ patch("openexecutive.audit.log_event", lambda *a, **k: None),+ ):+ asyncio.run(_drain(Session()))+ asyncio.run(_drain(Session(voice_persona_slug="supportive")))+ ov_mod.invalidate_cache()+ assert bodies == [+ get_active_body("analytical", db_path=_isolated),+ get_active_body("supportive", db_path=_isolated),+ ]diff --git a/packages/ui/src/app/council/page.tsx b/packages/ui/src/app/council/page.tsxindex 118ef939..3f78e105 100644--- a/packages/ui/src/app/council/page.tsx+++ b/packages/ui/src/app/council/page.tsx@@ -85,6 +85,17 @@ const ROUTE_TEXT: Record<ModelOption["route"], string> = {local: "local backend",};+function personaOption(p: PersonaMeta) {+ return (+ <option key={p.slug} value={p.slug}>+ {p.display_name}+ {p.is_builtin && !p.is_customized ? " · built-in" : ""}+ {p.is_customized ? " · customized" : ""}+ {!p.is_builtin ? " · custom" : ""}+ </option>+ );+}+function detailToDraft(d: AgentDetail): DraftState {return {role: d.role,@@ -759,14 +770,12 @@ export default function CouncilPage() {onChange={(e) => setDraft({ ...draft, voice_persona_slug: e.target.value === "default" ? null : e.target.value })}className="w-full px-3 py-2 rounded-lg bg-surface border border-line text-fg focus:border-indigo-500/40 focus:outline-none text-sm">- {personas.map((p) => (- <option key={p.slug} value={p.slug}>- {p.display_name}- {p.is_builtin && !p.is_customized ? " · built-in" : ""}- {p.is_customized ? " · customized" : ""}- {!p.is_builtin ? " · custom" : ""}- </option>- ))}+ {personas.filter((p) => !p.is_legacy).map(personaOption)}+ {personas.some((p) => p.is_legacy) && (+ <optgroup label="Legacy voices">+ {personas.filter((p) => p.is_legacy).map(personaOption)}+ </optgroup>+ )}</select><p className="text-[10px] text-fg-subtle mt-1">Selection saves with the main Save button above.diff --git a/packages/ui/src/app/onboard/page.tsx b/packages/ui/src/app/onboard/page.tsxindex 6563d929..9a1cdc04 100644--- a/packages/ui/src/app/onboard/page.tsx+++ b/packages/ui/src/app/onboard/page.tsx@@ -7,6 +7,7 @@ import OnboardConversation, {type Bubble,} from "@/components/onboard/OnboardConversation";import OnboardDraftReview from "@/components/onboard/OnboardDraftReview";+import VoicePicker from "@/components/executive/VoicePicker";import RoleFields from "@/components/workspace/RoleFields";import { useWorkspace } from "@/components/workspace/WorkspaceContext";import { updateWorkspace, type OnboardTurn, type WorkspaceMode } from "@/lib/api";@@ -22,6 +23,8 @@ import { roleFormErrors, roleFormFrom, roleUpdate, type RoleForm } from "@/lib/p// your role is — owner, an executive inside an organisation, independent —// saved with the workspace settings too (skippable; editable in Settings),// so setup asks the right questions and the Executive advises for that role.+// Either way it then asks how the Executive should sound: Direct, Supportive+// or Analytical (skippable; changeable in Settings).// A re-run — a company profile already exists — skips both: they are changed// in Settings, and the flow below follows whatever they currently are.//@@ -184,6 +187,8 @@ function WorkspaceChoice({ onChosen }: { onChosen: (mode: WorkspaceMode) => voidconst [error, setError] = useState<string | null>(null);// "Just me" was saved: ask the role before moving on.const [askRole, setAskRole] = useState(false);+ // The mode (and role) are saved: ask for the voice, then move on.+ const [askVoice, setAskVoice] = useState<WorkspaceMode | null>(null);async function choose(mode: WorkspaceMode) {if (saving) return;@@ -205,14 +210,24 @@ function WorkspaceChoice({ onChosen }: { onChosen: (mode: WorkspaceMode) => voidsetSaving(null);return;}- onChosen(mode);+ setAskVoice(mode);+ setSaving(null);} catch (err) {setError(err instanceof Error ? err.message : "Could not save your choice.");setSaving(null);}}- if (askRole) return <RoleStep onDone={() => onChosen("solo")} />;+ if (askVoice) return <VoiceStep onDone={() => onChosen(askVoice)} />;+ if (askRole)+ return (+ <RoleStep+ onDone={() => {+ setAskRole(false);+ setAskVoice("solo");+ }}+ />+ );return (<div className="max-w-2xl mx-auto px-6 py-16 w-full">@@ -328,6 +343,23 @@ function RoleStep({ onDone }: { onDone: () => void }) {);}+// How should the Executive sound? Saved on the Executive (PATCH+// /agents/executive); skipping keeps Direct. Settings → Executive changes it.+function VoiceStep({ onDone }: { onDone: () => void }) {+ return (+ <div className="max-w-3xl mx-auto px-6 py-16 w-full">+ <h1 className="text-xl font-semibold text-fg">How should your Executive sound?</h1>+ <p className="text-sm text-fg-muted mt-1">+ The advice is the same; this sets the tone it comes in. You can change it later in+ Settings.+ </p>+ <div className="mt-8">+ <VoicePicker variant="step" onDone={onDone} />+ </div>+ </div>+ );+}+export default function OnboardPage() {return (<div className="flex flex-col h-full bg-surface">diff --git a/packages/ui/src/app/settings/page.tsx b/packages/ui/src/app/settings/page.tsxindex 2b07640f..557f4026 100644--- a/packages/ui/src/app/settings/page.tsx+++ b/packages/ui/src/app/settings/page.tsx@@ -4,6 +4,7 @@ import Link from "next/link";import { useEffect, useMemo, useRef, useState } from "react";import ExecutiveRunSwitch from "@/components/executive/ExecutiveRunSwitch";+import VoicePicker from "@/components/executive/VoicePicker";import Icon from "@/components/Icon";import ActAsMeCard from "@/components/settings/ActAsMeCard";import SettingsNav from "@/components/settings/SettingsNav";@@ -58,9 +59,15 @@ export default function SettingsPage() {<SettingsSectionid="executive"title="Executive"- description="Whether the Executive is doing its own work — briefs, nudges, monitoring, inbox, workflow timers — or holding it."+ description="Whether the Executive is doing its own work — briefs, nudges, monitoring, inbox, workflow timers — or holding it, and the voice it answers in."><ExecutiveRunSwitch variant="card" />+ <div className="mt-6">+ <h3 className="text-[10px] font-semibold uppercase tracking-widest text-fg-subtle mb-2">+ Voice+ </h3>+ <VoicePicker variant="card" />+ </div></SettingsSection><SettingsSectiondiff --git a/packages/ui/src/components/executive/VoicePicker.tsx b/packages/ui/src/components/executive/VoicePicker.tsxnew file mode 100644index 00000000..d130d514--- /dev/null+++ b/packages/ui/src/components/executive/VoicePicker.tsx@@ -0,0 +1,156 @@+"use client";++import { useEffect, useState } from "react";++import { getAgentDetail, listPersonas, patchAgent, type PersonaMeta } from "@/lib/api";++// The Executive's voice, picked from the three general voices. Shared by the+// setup flow (/onboard) and Settings; both save through PATCH+// /agents/executive, the same field the Agent Council edits.+//+// Named built-in voices are legacy: hidden here, but an install that already+// uses one (or a custom voice made in the Council) sees it listed as its+// current voice, so picking never hides what is active.++// `default` is the Direct voice; it is stored as no override.+const DIRECT = "default";+const GENERAL_ORDER = [DIRECT, "supportive", "analytical"];++export function generalVoices(all: PersonaMeta[]): PersonaMeta[] {+ return GENERAL_ORDER.map((slug) => all.find((p) => p.slug === slug)).filter(+ (p): p is PersonaMeta => p !== undefined && !p.is_legacy,+ );+}++interface Props {+ // "card" saves on each pick (Settings). "step" saves on Continue (setup).+ variant: "card" | "step";+ onDone?: () => void;+}++export default function VoicePicker({ variant, onDone }: Props) {+ const [voices, setVoices] = useState<PersonaMeta[]>([]);+ const [current, setCurrent] = useState<string>(DIRECT);+ const [picked, setPicked] = useState<string>(DIRECT);+ const [loaded, setLoaded] = useState(false);+ const [saving, setSaving] = useState(false);+ const [error, setError] = useState<string | null>(null);++ useEffect(() => {+ let cancelled = false;+ Promise.all([listPersonas(), getAgentDetail("executive")])+ .then(([all, exec]) => {+ if (cancelled) return;+ const slug = exec.voice_persona_slug ?? DIRECT;+ const shown = generalVoices(all);+ const active = all.find((p) => p.slug === slug);+ if (active && !shown.some((p) => p.slug === slug)) shown.push(active);+ setVoices(shown);+ setCurrent(slug);+ setPicked(slug);+ setLoaded(true);+ })+ .catch(() => {+ if (!cancelled) setError("Could not load the voices.");+ });+ return () => {+ cancelled = true;+ };+ }, []);++ async function save(slug: string): Promise<boolean> {+ if (slug === current) return true;+ setSaving(true);+ setError(null);+ try {+ const updated = await patchAgent("executive", {+ voice_persona_slug: slug === DIRECT ? null : slug,+ });+ setCurrent(updated.voice_persona_slug ?? DIRECT);+ return true;+ } catch (err) {+ setError(err instanceof Error ? err.message : "Could not save the voice.");+ setPicked(current);+ return false;+ } finally {+ setSaving(false);+ }+ }++ async function pick(slug: string) {+ setPicked(slug);+ if (variant === "card") await save(slug);+ }++ async function continueStep() {+ if (await save(picked)) onDone?.();+ }++ return (+ <div>+ <div role="radiogroup" aria-label="Executive voice" className="grid gap-3 sm:grid-cols-3">+ {voices.map((v) => {+ const selected = picked === v.slug;+ return (+ <button+ key={v.slug}+ type="button"+ role="radio"+ aria-checked={selected}+ onClick={() => void pick(v.slug)}+ disabled={saving || !loaded}+ className={`flex flex-col justify-start text-left rounded-xl border p-4 transition-colors cursor-pointer disabled:cursor-not-allowed focus:outline-none focus:ring-2 focus:ring-indigo-500/50 ${+ selected+ ? "border-indigo-500/60 bg-indigo-500/10"+ : "border-line bg-surface-elevated hover:border-indigo-500/40"+ }`}+ >+ <span className="block text-sm font-semibold text-fg">{v.display_name}</span>+ {v.description ? (+ <span className="block text-xs text-fg-muted mt-1 leading-relaxed">+ {v.description}+ </span>+ ) : (+ <span className="block text-xs text-fg-muted mt-1">Your current voice</span>+ )}+ {v.sample && (+ <span className="block text-xs text-fg-subtle italic mt-3 leading-relaxed">+ “{v.sample}”+ </span>+ )}+ </button>+ );+ })}+ </div>++ {error && <p className="mt-3 text-xs text-red-400">{error}</p>}++ {variant === "card" && (+ <p className="mt-3 text-xs text-fg-subtle">+ {saving ? "Saving…" : "Applies from the next message. The Agent Council has more voices."}+ </p>+ )}++ {variant === "step" && (+ <div className="mt-6 flex items-center gap-3">+ <button+ type="button"+ onClick={() => void continueStep()}+ disabled={saving || !loaded}+ className="px-4 py-2 rounded-lg text-sm font-medium bg-indigo-500 hover:bg-indigo-600 text-white transition-colors cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"+ >+ {saving ? "Saving…" : "Continue"}+ </button>+ <button+ type="button"+ onClick={onDone}+ disabled={saving}+ className="px-3 py-2 rounded-lg text-sm text-fg-muted hover:text-fg transition-colors cursor-pointer disabled:opacity-50"+ >+ Skip for now+ </button>+ </div>+ )}+ </div>+ );+}diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.tsindex 035ddf59..4a353623 100644--- a/packages/ui/src/lib/api.ts+++ b/packages/ui/src/lib/api.ts@@ -2560,6 +2560,11 @@ export interface PersonaMeta {display_name: string;is_builtin: boolean;is_customized: boolean;+ // Hidden from the voice picker but still loadable (named built-in voices).+ is_legacy: boolean;+ // Picker copy from a built-in voice's frontmatter ("" for custom voices).+ description: string;+ sample: string;}export interface Persona {@@ -2569,6 +2574,9 @@ export interface Persona {is_builtin: boolean;is_customized: boolean;source_notes: string;+ is_legacy: boolean;+ description: string;+ sample: string;}export async function listPersonas(): Promise<PersonaMeta[]> {