Skip to content

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

Record usage for specialist consults in BaseAgent.analyze

Rufus425eea63ef3e
diff --git a/packages/core/openexecutive/agents/base.py b/packages/core/openexecutive/agents/base.py
index 82628e5e..06ca9161 100644
--- a/packages/core/openexecutive/agents/base.py
+++ b/packages/core/openexecutive/agents/base.py
@@ -59,7 +59,16 @@ class BaseAgent(ABC):
system_prompt_override: str | None = None,
model_override: str | None = None,
deep_reasoning_override: bool | None = None,
+ actor: str = "specialist",
) -> 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.
+ """
settings = get_settings()
# Resolution order: explicit kwarg (for sandbox/test calls) → DB
@@ -141,6 +150,7 @@ class BaseAgent(ABC):
# wiring lands in the next commit.
provider = get_provider(model)
message = await provider.messages_create(**create_kwargs)
+ log_model_usage(message, model=model, actor=actor)
text_blocks = [b for b in message.content if b.type == "text"]
if not text_blocks:
diff --git a/packages/core/openexecutive/api/routes/agents.py b/packages/core/openexecutive/api/routes/agents.py
index b0243ffd..f3328272 100644
--- a/packages/core/openexecutive/api/routes/agents.py
+++ b/packages/core/openexecutive/api/routes/agents.py
@@ -496,6 +496,9 @@ async def test_agent(agent_id: str, req: AgentTestRequest) -> AgentTestResponse:
system_prompt_override=req.prompt,
model_override=req.model,
deep_reasoning_override=req.use_deep_reasoning,
+ # Sandbox runs must not read as production specialist spend in
+ # the /audit/usage by-source breakdown.
+ actor="agent_test",
)
except Exception as exc: # noqa: BLE001
logger.exception("Agent test failed for %r", agent_id)
diff --git a/packages/core/openexecutive/api/routes/audit.py b/packages/core/openexecutive/api/routes/audit.py
index a13469a1..562804eb 100644
--- a/packages/core/openexecutive/api/routes/audit.py
+++ b/packages/core/openexecutive/api/routes/audit.py
@@ -134,8 +134,9 @@ class UsageByModel(UsageTotals):
class UsageBySource(UsageTotals):
"""One row per call source (the audit `actor`): `executive` chat turns,
- `specialist_research`, `research_synthesis`, `research_watchlist`,
- `triage`, `memory_extractor`, … — so a heavy day can be traced to the
+ `specialist` consults, `specialist_research`, `research_synthesis`,
+ `research_watchlist`, `triage`, `memory_extractor`, … — 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 457ac76b..224b36fe 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_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` 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).
- 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 abd68249..e8fdefb3 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, 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, 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 2b865436..6679e65c 100644
--- a/packages/core/openexecutive/audit/usage.py
+++ b/packages/core/openexecutive/audit/usage.py
@@ -1,16 +1,17 @@
"""Per-call model usage recording.
-Every model call the system makes (Executive chat turns, 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,
+specialist research, the research synthesis and watchlist passes, triage, the
+chat memory extractor) 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_research``, ``research_synthesis``, ``research_watchlist``,
-``triage``, ``memory_extractor``), which is what the per-source breakdown
+``specialist`` for chat-turn consults, ``specialist_research``,
+``research_synthesis``, ``research_watchlist``, ``triage``,
+``memory_extractor``), 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/tests/unit/test_usage_recording.py b/packages/core/tests/unit/test_usage_recording.py
index 3507d42b..09659319 100644
--- a/packages/core/tests/unit/test_usage_recording.py
+++ b/packages/core/tests/unit/test_usage_recording.py
@@ -1,6 +1,7 @@
"""Every model call site records a ``cache_event`` usage row: specialist
-tool calls, triage, and the chat memory extractor (the Executive's own
-turns and the research loops are covered by their module tests)."""
+consults, specialist tool calls, triage, and the chat memory extractor (the
+Executive's own turns and the research loops are covered by their module
+tests)."""
from __future__ import annotations
import asyncio
@@ -58,6 +59,47 @@ def test_analyze_with_tools_records_usage_under_the_callers_actor(
assert rows[0].details["web_search_requests"] == 3
+def test_analyze_records_usage_as_specialist(
+ audit: AuditLogger, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A chat-turn consult (``consult_specialist`` → ``analyze``) writes one
+ usage row under the default ``specialist`` actor, so the session cost
+ summary and ``/audit/usage`` count it."""
+ monkeypatch.setattr("openexecutive.agents.overrides.get_override", lambda _name: None)
+ response = _response(input_tokens=120, output_tokens=40, cache_read_input_tokens=100)
+ response.content = [SimpleNamespace(type="text", text="analysis")]
+ provider = SimpleNamespace(messages_create=AsyncMock(return_value=response))
+ monkeypatch.setattr("openexecutive.agents.base.get_provider", lambda _m: provider)
+
+ text = asyncio.run(_Agent().analyze("What should we do?"))
+
+ assert text == "analysis"
+ rows = audit.query(event_type="cache_event")
+ assert len(rows) == 1
+ assert rows[0].actor == "specialist"
+ assert rows[0].details["model"] == "claude-test"
+ assert rows[0].details["input_tokens"] == 120
+ assert rows[0].details["output_tokens"] == 40
+ assert rows[0].details["cache_read_input_tokens"] == 100
+
+
+def test_analyze_records_usage_under_an_explicit_actor(
+ audit: AuditLogger, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The Council test box passes ``actor="agent_test"`` so sandbox runs
+ are separable from production consults in the by-source breakdown."""
+ monkeypatch.setattr("openexecutive.agents.overrides.get_override", lambda _name: None)
+ response = _response(input_tokens=5, output_tokens=1)
+ 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)
+
+ asyncio.run(_Agent().analyze("q", actor="agent_test"))
+
+ rows = audit.query(event_type="cache_event")
+ assert [r.actor for r in rows] == ["agent_test"]
+
+
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 4b7460ac..df6783a0 100644
--- a/packages/ui/src/lib/api.ts
+++ b/packages/ui/src/lib/api.ts
@@ -1630,8 +1630,9 @@ export interface UsageByModel extends UsageTotals {
model: string;
}
-// One row per call source (the audit `actor`): executive, specialist_research,
-// research_synthesis, research_watchlist, triage, memory_extractor, …
+// One row per call source (the audit `actor`): executive, specialist,
+// specialist_research, research_synthesis, research_watchlist, triage,
+// memory_extractor, …
export interface UsageBySource extends UsageTotals {
source: string;
}