AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
Split the specialist usage actor by call path
Rufus4a434392e340
diff --git a/packages/core/openexecutive/agents/base.py b/packages/core/openexecutive/agents/base.pyindex 06ca9161..1ad13be1 100644--- a/packages/core/openexecutive/agents/base.py+++ b/packages/core/openexecutive/agents/base.py@@ -63,11 +63,11 @@ class BaseAgent(ABC):) -> str:"""Run one prose specialist call and return its text.- Every call records a ``cache_event`` usage row under ``actor`` (the- Executive's ``consult_specialist`` path uses the default; the- Council test box passes ``agent_test``), so consults count toward- the session cost summary and ``/audit/usage`` like every other- model call.+ Every call records a ``cache_event`` usage row under ``actor``, so+ the call counts toward the session cost summary and ``/audit/usage``+ like every other model call. The router sets ``actor`` per path+ (``specialist`` for chat-turn consults, ``specialist_workflow`` for+ workflow steps); the Council test box passes ``agent_test``."""settings = get_settings()diff --git a/packages/core/openexecutive/api/routes/agents.py b/packages/core/openexecutive/api/routes/agents.pyindex f3328272..72ef6c5f 100644--- a/packages/core/openexecutive/api/routes/agents.py+++ b/packages/core/openexecutive/api/routes/agents.py@@ -17,6 +17,7 @@ from openexecutive.agents.overrides import (rollback_to,set_override,)+from openexecutive.audit.usage import log_model_usagelogger = logging.getLogger(__name__)@@ -460,6 +461,7 @@ async def _test_executive(req: AgentTestRequest) -> str:],messages=[{"role": "user", "content": req.query}],)+ log_model_usage(message, model=model, actor="agent_test")text_blocks = [b for b in message.content if b.type == "text"]return text_blocks[0].text if text_blocks else ""diff --git a/packages/core/openexecutive/api/routes/audit.py b/packages/core/openexecutive/api/routes/audit.pyindex 562804eb..87a334fb 100644--- a/packages/core/openexecutive/api/routes/audit.py+++ b/packages/core/openexecutive/api/routes/audit.py@@ -134,9 +134,10 @@ class UsageByModel(UsageTotals):class UsageBySource(UsageTotals):"""One row per call source (the audit `actor`): `executive` chat turns,- `specialist` consults, `specialist_research`, `research_synthesis`,- `research_watchlist`, `triage`, `memory_extractor`, … — so a heavy day- can be traced to the+ `specialist` chat-turn consults, `specialist_workflow` steps,+ `specialist_research`, `research_synthesis`, `research_watchlist`,+ `triage`, `memory_extractor`, `agent_test`, … — so a heavy day can be+ traced to thepart of the system that produced it."""source: strdiff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yamlindex 224b36fe..4bf2b2be 100644--- a/packages/core/openexecutive/architecture/architecture-facts.yaml+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml@@ -1384,7 +1384,7 @@ audit:- alert — alert created by the triage pipeline- integration_inbound — Slack / Discord / email / Telegram / Google Chat message received- knowledge_retrieval — one row per `knowledge.retriever.retrieve()` call; details carry chunk counts + domains, full payload carries each chunk's source, distance, and text preview so the session view shows "which RAG chunks influenced this response"- - cache_event — one row per model call, from every call site (`audit.usage.log_model_usage`): Executive iterations and the committee revision pass (`actor` executive / committee_revision), `BaseAgent.analyze` consults made by `consult_specialist` (`actor` specialist; the Council test box tags its sandbox calls `agent_test`), `BaseAgent.analyze_with_tools` callers (specialist_research, query_watch, signal_enrichment), the research synthesis and watchlist passes (research_synthesis / research_watchlist), triage, and the chat memory extractor (memory_extractor). Captures `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `cost_usd`, `web_search_requests` (from `usage.server_tool_use`), `stop_reason`, and — inside a research run — the run's `run_id`, so prompt-cache hits are visible per turn, plus `cost_usd` — the actual USD OpenRouter charged for the call (read from `usage.cost`; null on the Anthropic-direct path or for rows logged before cost capture shipped). This is the token-usage + cost source of truth aggregated by both `/audit/sessions/{id}` (per session) and `/audit/usage` (cross-session).+ - cache_event — one row per model call, from every call site (`audit.usage.log_model_usage`): Executive iterations and the committee revision pass (`actor` executive / committee_revision), `BaseAgent.analyze` callers — chat-turn consults via `route_parallel` (`actor` specialist), workflow steps and other direct `route_to_specialist` callers (specialist_workflow), the MCP `consult_specialist` tool (specialist_mcp), and both Council test boxes (agent_test) — `BaseAgent.analyze_with_tools` callers (specialist_research, query_watch, signal_enrichment), the research synthesis and watchlist passes (research_synthesis / research_watchlist), triage, and the chat memory extractor (memory_extractor). Captures `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `cost_usd`, `web_search_requests` (from `usage.server_tool_use`), `stop_reason`, and — inside a research run — the run's `run_id`, so prompt-cache hits are visible per turn, plus `cost_usd` — the actual USD OpenRouter charged for the call (read from `usage.cost`; null on the Anthropic-direct path or for rows logged before cost capture shipped). This is the token-usage + cost source of truth aggregated by both `/audit/sessions/{id}` (per session) and `/audit/usage` (cross-session).- memory_snapshot — one row at Executive turn entry; captures the system-block layout, conversation history length, episodic context (full text in `full_json`), and a company-profile hash so the session view can render "what the agent saw" before any API call- committee_review — one row per committee-reviewed turn; carries draft length, final length, per-reviewer critiques and timings (previously emitted but newly declared as a recognised event_type)- peer_memory — one row per `openexecutive.memory.honcho_client` call (prefetch / sync_turn / directional_chat / prefetch_department / sync_department_turn / append_department_note); carries `op`, `person_id`, optional `department_slug`, `outcome` (ok / timeout / error / disabled / no_person / no_department / no_loop / empty), `duration_ms`, plus op-specific details (query preview, reasoning_level, peer count, co_present_person_ids, co_present_department_slugs, originating_person_id, target_person_id, session_id, kind) so the flow-chart view renders the peer_memory path alongside `<retrieved_context>` and `<past_decisions>`. Disabled / no-Person / no-Department turns still emit (outcome marker) so audit absence equals "code path never ran" instead of "the provider was down."diff --git a/packages/core/openexecutive/architecture/prebuilt/audit.json b/packages/core/openexecutive/architecture/prebuilt/audit.jsonindex e8fdefb3..a9226677 100644--- a/packages/core/openexecutive/architecture/prebuilt/audit.json+++ b/packages/core/openexecutive/architecture/prebuilt/audit.json@@ -1,7 +1,7 @@{"section_id": "audit","title": "Audit Log",- "markdown": "The audit log is a persistent, searchable, append-only record of what the system did — distinct from episodic memory (which biases future LLM behavior). Every event flows through `audit/logger.log_event`, a synchronous SQLite writer (WAL + 5s busy_timeout) that appends one row to the `audit_log` table in `episodic_memory.db`.\n\n### Event types\nRows are tagged by `event_type`, including `chat_turn`, `specialist_consult`, `tool_invocation`, `scheduled_action`, `alert`, `integration_inbound` (Slack / Discord / email / Telegram / Google Chat), plus `knowledge_retrieval`, `cache_event` (one row per model call from every call site — Executive turns, specialist consults, research specialists, the research routing and watchlist passes, triage, memory extraction — carrying tokens, cache hits, cost, server-side search count and, inside a research run, its `run_id`), `memory_snapshot`, `committee_review`, `peer_memory`, and the external-signal/monitor events.\n\n### Session & turn context\nEach row carries `session_id`, `turn_id`, `actor`, `summary`, `details_json`, `full_json`, and `department`. A `turn_id` (`f\"t-{uuid12}\"`) is set per Executive turn and propagated automatically via ContextVars to retriever / specialist / tool / cache emits, grouping one user-assistant exchange. `summary` is the searchable column (LIKE, ~300 char cap); `details_json` is structured and not searched.\n\n### Views\n- `GET /audit` — filterable list with a \"Group by session\" toggle and session pills.\n- `GET /audit/session/{id}` — full ordered timeline plus a server-derived node/edge graph rendered as a three-pane React Flow chart.\n\n### Invariant\nAudit writes never break a chat turn: all writes swallow exceptions and log a warning, and instrumentation observes only — it never touches request building or the cached prompt blocks. Audit is append-only: no UPDATE or DELETE paths exist in product code.",+ "markdown": "The audit log is a persistent, searchable, append-only record of what the system did — distinct from episodic memory (which biases future LLM behavior). Every event flows through `audit/logger.log_event`, a synchronous SQLite writer (WAL + 5s busy_timeout) that appends one row to the `audit_log` table in `episodic_memory.db`.\n\n### Event types\nRows are tagged by `event_type`, including `chat_turn`, `specialist_consult`, `tool_invocation`, `scheduled_action`, `alert`, `integration_inbound` (Slack / Discord / email / Telegram / Google Chat), plus `knowledge_retrieval`, `cache_event` (one row per model call from every call site — Executive turns, specialist consults (chat turns and workflow steps), research specialists, the research routing and watchlist passes, triage, memory extraction — carrying tokens, cache hits, cost, server-side search count and, inside a research run, its `run_id`), `memory_snapshot`, `committee_review`, `peer_memory`, and the external-signal/monitor events.\n\n### Session & turn context\nEach row carries `session_id`, `turn_id`, `actor`, `summary`, `details_json`, `full_json`, and `department`. A `turn_id` (`f\"t-{uuid12}\"`) is set per Executive turn and propagated automatically via ContextVars to retriever / specialist / tool / cache emits, grouping one user-assistant exchange. `summary` is the searchable column (LIKE, ~300 char cap); `details_json` is structured and not searched.\n\n### Views\n- `GET /audit` — filterable list with a \"Group by session\" toggle and session pills.\n- `GET /audit/session/{id}` — full ordered timeline plus a server-derived node/edge graph rendered as a three-pane React Flow chart.\n\n### Invariant\nAudit writes never break a chat turn: all writes swallow exceptions and log a warning, and instrumentation observes only — it never touches request building or the cached prompt blocks. Audit is append-only: no UPDATE or DELETE paths exist in product code.","mermaid": "flowchart TD\n Chat[\"Chat turn / consult / tool call\"]\n Sched[\"Scheduled action\"]\n Inbound[\"Inbound integration\"]\n Log[\"audit/logger.log_event\"]\n DB[\"audit_log table (append-only)\"]\n ListView[\"/audit list view\"]\n SessView[\"/audit/session/{id} flow chart\"]\n Chat -->|event + turn_id| Log\n Sched --> Log\n Inbound --> Log\n Log -->|swallow errors, never block| DB\n DB --> ListView\n DB --> SessView\n class Chat entry\n class Sched entry\n class Inbound entry\n class Log compute\n class DB storage\n class ListView hot\n class SessView hot","generated_at": "2026-06-01T00:00:00+00:00"}diff --git a/packages/core/openexecutive/audit/usage.py b/packages/core/openexecutive/audit/usage.pyindex 6679e65c..160549be 100644--- a/packages/core/openexecutive/audit/usage.py+++ b/packages/core/openexecutive/audit/usage.py@@ -1,17 +1,20 @@"""Per-call model usage recording.-Every model call the system makes (Executive chat turns, specialist consults,-specialist research, the research synthesis and watchlist passes, triage, the-chat memory extractor) records one ``cache_event`` audit row through+Every model call the system makes (Executive chat turns, specialist consults+and workflow specialist steps, specialist research, the research synthesis+and watchlist passes, triage, the chat memory extractor, the Council test+boxes) records one ``cache_event`` audit row through:func:`log_model_usage` — tokens, cache hits, provider-reported cost, and theserver-side web searches the call made. ``GET /audit/usage`` and theper-session cost view sum those rows, so a run's weight can be read from theaudit log instead of guessed.The ``actor`` column names the source of the call (``executive``,-``specialist`` for chat-turn consults, ``specialist_research``,+``specialist`` for chat-turn consults, ``specialist_workflow`` for workflow+steps, ``specialist_mcp`` for the MCP consult tool, ``specialist_research``,``research_synthesis``, ``research_watchlist``, ``triage``,-``memory_extractor``), which is what the per-source breakdown+``memory_extractor``, ``agent_test`` for the Council test boxes), which is+what the per-source breakdowngroups on. A research run binds its ``run_id`` in a ContextVar for itsduration so every row the run produces carries it in ``details``; theworkflow then rolls those rows up into the ``usage`` block on its result.diff --git a/packages/core/openexecutive/mcp_server/server.py b/packages/core/openexecutive/mcp_server/server.pyindex d0da11fa..e012b9eb 100644--- a/packages/core/openexecutive/mcp_server/server.py+++ b/packages/core/openexecutive/mcp_server/server.py@@ -308,7 +308,9 @@ async def consult_specialist(if specialist not in SPECIALIST_REGISTRY:valid = ", ".join(sorted(SPECIALIST_REGISTRY))raise ValueError(f"Unknown specialist {specialist!r}. Valid: {valid}")- return await route_to_specialist(specialist, query, context=context)+ return await route_to_specialist(+ specialist, query, context=context, actor="specialist_mcp",+ )@mcp.tool()diff --git a/packages/core/openexecutive/orchestrator/router.py b/packages/core/openexecutive/orchestrator/router.pyindex f6b03f35..e3d0d4af 100644--- a/packages/core/openexecutive/orchestrator/router.py+++ b/packages/core/openexecutive/orchestrator/router.py@@ -84,7 +84,16 @@ async def route_to_specialist(episodic_context: str = "",failure_cases: str = "",department_memory: str = "",+ actor: str = "specialist_workflow",) -> str:+ """Run one specialist and return its prose analysis.++ ``actor`` names the caller on the ``cache_event`` usage row the call+ records. Direct callers are workflow steps (hence the default);+ ``route_parallel`` passes ``specialist`` for the Executive's chat-turn+ consults so the two stay separable in the ``/audit/usage`` by-source+ breakdown.+ """agent = SPECIALIST_REGISTRY.get(specialist_name)if agent is None:return f"Unknown specialist: {specialist_name}"@@ -95,6 +104,7 @@ async def route_to_specialist(episodic_context=episodic_context,failure_cases=failure_cases,department_memory=department_memory,+ actor=actor,)@@ -258,6 +268,7 @@ async def route_parallel(episodic_context=episodic_context,failure_cases=failures_per_call[idx],department_memory=dept_memory_per_call[idx],+ actor="specialist",)if debug_collector:debug_collector.emit("specialist_done", {diff --git a/packages/core/tests/unit/test_mcp_server.py b/packages/core/tests/unit/test_mcp_server.pyindex 9f7e5b2f..d00d9f7f 100644--- a/packages/core/tests/unit/test_mcp_server.py+++ b/packages/core/tests/unit/test_mcp_server.py@@ -145,7 +145,9 @@ async def test_consult_specialist_routes_to_specialist() -> None:with patch("openexecutive.orchestrator.router.route_to_specialist", new=mock):out = await mcp_server.consult_specialist("cfo", "runway?", "context here")assert out == "CFO analysis"- mock.assert_awaited_once_with("cfo", "runway?", context="context here")+ mock.assert_awaited_once_with(+ "cfo", "runway?", context="context here", actor="specialist_mcp",+ )@pytest.mark.asynciodiff --git a/packages/core/tests/unit/test_router.py b/packages/core/tests/unit/test_router.pyindex 53d4440a..30e6c68f 100644--- a/packages/core/tests/unit/test_router.py+++ b/packages/core/tests/unit/test_router.py@@ -39,9 +39,22 @@ def test_route_to_specialist_passes_episodic_to_analyze() -> None:episodic_context="EPISODIC",failure_cases="",department_memory="",+ actor="specialist_workflow",)+def test_route_parallel_tags_chat_consults_with_the_specialist_actor() -> None:+ cso_mock = AsyncMock(return_value="x")+ with patch.object(SPECIALIST_REGISTRY["cso"], "analyze", cso_mock):+ asyncio.run(+ route_parallel(+ [{"specialist": "cso", "query": "q"}],+ retrieved_knowledge_map={"cso": ""},+ )+ )+ assert cso_mock.await_args.kwargs["actor"] == "specialist"++def test_route_to_specialist_defaults_episodic_to_empty_string() -> None:analyze_mock = AsyncMock(return_value="x")with patch.object(SPECIALIST_REGISTRY["cfo"], "analyze", analyze_mock):diff --git a/packages/core/tests/unit/test_router_department_memory.py b/packages/core/tests/unit/test_router_department_memory.pyindex ab739741..9a739d5b 100644--- a/packages/core/tests/unit/test_router_department_memory.py+++ b/packages/core/tests/unit/test_router_department_memory.py@@ -35,6 +35,7 @@ def stub_agents(monkeypatch: pytest.MonkeyPatch) -> dict[str, list[dict[str, Anyepisodic_context: str = "",failure_cases: str = "",department_memory: str = "",+ actor: str = "specialist",) -> str:received.setdefault(self.name, []).append({diff --git a/packages/core/tests/unit/test_router_retrieval.py b/packages/core/tests/unit/test_router_retrieval.pyindex 40b8c62e..8e5e34bd 100644--- a/packages/core/tests/unit/test_router_retrieval.py+++ b/packages/core/tests/unit/test_router_retrieval.py@@ -27,6 +27,7 @@ def stub_agents(monkeypatch: pytest.MonkeyPatch) -> dict[str, list[dict[str, Anyepisodic_context: str = "",failure_cases: str = "",department_memory: str = "",+ actor: str = "specialist",) -> str:received.setdefault(self.name, []).append({diff --git a/packages/core/tests/unit/test_usage_recording.py b/packages/core/tests/unit/test_usage_recording.pyindex 09659319..446363cc 100644--- a/packages/core/tests/unit/test_usage_recording.py+++ b/packages/core/tests/unit/test_usage_recording.py@@ -100,6 +100,53 @@ def test_analyze_records_usage_under_an_explicit_actor(assert [r.actor for r in rows] == ["agent_test"]+def test_route_to_specialist_tags_rows_with_the_active_turn(+ audit: AuditLogger, monkeypatch: pytest.MonkeyPatch,+) -> None:+ """A direct router call (a workflow step) records under the+ ``specialist_workflow`` actor and inherits the active audit turn, which+ is what lets ``/audit/sessions/{id}`` group the row under its turn."""+ from openexecutive.audit.context import set_turn+ from openexecutive.orchestrator import router++ monkeypatch.setattr("openexecutive.agents.overrides.get_override", lambda _name: None)+ monkeypatch.setitem(router.SPECIALIST_REGISTRY, "unit_agent", _Agent())+ response = _response(input_tokens=8, output_tokens=3)+ response.content = [SimpleNamespace(type="text", text="ok")]+ provider = SimpleNamespace(messages_create=AsyncMock(return_value=response))+ monkeypatch.setattr("openexecutive.agents.base.get_provider", lambda _m: provider)++ with set_turn(session_id="s-1", turn_id="t-1"):+ asyncio.run(router.route_to_specialist("unit_agent", "q"))++ rows = audit.query(event_type="cache_event")+ assert len(rows) == 1+ assert rows[0].actor == "specialist_workflow"+ assert rows[0].session_id == "s-1"+ assert rows[0].turn_id == "t-1"+++def test_executive_test_box_records_usage(+ audit: AuditLogger, monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The Council's Executive preview is a raw provider call; it records+ under ``agent_test`` like the specialist test box."""+ from openexecutive.api.routes.agents import AgentTestRequest, _test_executive++ monkeypatch.setattr("openexecutive.api.routes.agents.get_override", lambda _name: None)+ response = _response(input_tokens=9, output_tokens=2)+ response.content = [SimpleNamespace(type="text", text="preview")]+ provider = SimpleNamespace(messages_create=AsyncMock(return_value=response))+ monkeypatch.setattr("openexecutive.providers.get_provider", lambda _m: provider)++ text = asyncio.run(_test_executive(AgentTestRequest(query="hi", prompt="P", model="claude-x")))++ assert text == "preview"+ rows = audit.query(event_type="cache_event")+ assert [r.actor for r in rows] == ["agent_test"]+ assert rows[0].details["model"] == "claude-x"++def test_triage_records_usage(audit: AuditLogger) -> None:from openexecutive.agents.triage import TriageAgentfrom openexecutive.alerts.models import AlertEventdiff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.tsindex df6783a0..dd6ded93 100644--- a/packages/ui/src/lib/api.ts+++ b/packages/ui/src/lib/api.ts@@ -1631,8 +1631,8 @@ export interface UsageByModel extends UsageTotals {}// One row per call source (the audit `actor`): executive, specialist,-// specialist_research, research_synthesis, research_watchlist, triage,-// memory_extractor, …+// specialist_workflow, specialist_research, research_synthesis,+// research_watchlist, triage, memory_extractor, agent_test, …export interface UsageBySource extends UsageTotals {source: string;}