Skip to content

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.py
index 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.py
index 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_usage
logger = 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.py
index 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 the
part of the system that produced it."""
source: str
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index 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.json
index 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.py
index 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 the
server-side web searches the call made. ``GET /audit/usage`` and the
per-session cost view sum those rows, so a run's weight can be read from the
audit 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 breakdown
groups on. A research run binds its ``run_id`` in a ContextVar for its
duration so every row the run produces carries it in ``details``; the
workflow 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.py
index 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.py
index 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.py
index 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.asyncio
diff --git a/packages/core/tests/unit/test_router.py b/packages/core/tests/unit/test_router.py
index 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.py
index 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, Any
episodic_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.py
index 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, Any
episodic_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.py
index 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 TriageAgent
from openexecutive.alerts.models import AlertEvent
diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.ts
index 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;
}