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.pyindex 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.pyindex 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: BLE001logger.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.pyindex 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 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 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.jsonindex 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.pyindex 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 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_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 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/tests/unit/test_usage_recording.py b/packages/core/tests/unit/test_usage_recording.pyindex 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 annotationsimport 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 TriageAgentfrom openexecutive.alerts.models import AlertEventdiff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.tsindex 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;}