Skip to content

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

feat(audit): record every model call and roll a research run's usage up

Rufuse4ffbffb58a6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5d7f2620..52ac63bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -118,6 +118,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
routing pass can no longer start a workflow (`run_workflow` is withheld,
`suggest_workflow` remains); the periodic run's default interval moves
from 120 to 360 minutes.
+- **Every model call is recorded.** Research specialists, the research
+ routing and watchlist passes, triage and the chat memory extractor now
+ write the same `cache_event` audit row the Executive's chat turns always
+ did (tokens, cache hits, cost, and the server-side web searches the call
+ made). A research run's result and its `watchlist_research_periodic_ran`
+ audit row carry a `usage` block summing its calls per source, and
+ `GET /audit/usage` (and the usage page) gain a by-source breakdown.
### Removed
- **The xcrawl scrape service and everything that depended on it.** The
diff --git a/packages/core/openexecutive/agents/base.py b/packages/core/openexecutive/agents/base.py
index ba834cd1..82628e5e 100644
--- a/packages/core/openexecutive/agents/base.py
+++ b/packages/core/openexecutive/agents/base.py
@@ -4,6 +4,7 @@ import logging
from abc import ABC, abstractmethod
from typing import Any
+from openexecutive.audit.usage import log_model_usage
from openexecutive.config import get_settings
from openexecutive.providers import get_provider, model_supports_deep_reasoning
@@ -166,6 +167,7 @@ class BaseAgent(ABC):
timeout_seconds: float = _SPECIALIST_TIMEOUT,
model_override: str | None = None,
deep_reasoning_override: bool | None = None,
+ actor: str = "specialist_tools",
) -> Any:
"""Tool-use variant of ``analyze`` — returns the raw provider Message.
@@ -191,6 +193,10 @@ class BaseAgent(ABC):
reasoning off) without disturbing the agent's chat-time defaults. When
None, the per-instance effective_* values apply, matching prior
behavior.
+
+ ``actor`` names the caller on the ``cache_event`` usage row recorded
+ for the call (``specialist_research``, ``query_watch``, …), which is
+ what the per-source usage breakdown groups on.
"""
settings = get_settings()
system_prompt = self.effective_system_prompt() + (
@@ -228,4 +234,6 @@ class BaseAgent(ABC):
create_kwargs["max_tokens"] = max(max_tokens, 16000)
provider = get_provider(model)
- return await provider.messages_create(**create_kwargs)
+ message = await provider.messages_create(**create_kwargs)
+ log_model_usage(message, model=model, actor=actor)
+ return message
diff --git a/packages/core/openexecutive/agents/triage.py b/packages/core/openexecutive/agents/triage.py
index eda9a0f9..272050e6 100644
--- a/packages/core/openexecutive/agents/triage.py
+++ b/packages/core/openexecutive/agents/triage.py
@@ -10,6 +10,7 @@ from openexecutive.alerts.models import (
AlertSeverity,
TriageDecision,
)
+from openexecutive.audit.usage import log_model_usage
from openexecutive.providers import get_provider
if TYPE_CHECKING:
@@ -250,6 +251,7 @@ class TriageAgent(BaseAgent):
dedup_key=f"fallback-{event.source}-{event.external_id}",
reason_if_suppressed="triage_error",
)
+ log_model_usage(message, model=self.effective_model(), actor="triage")
for block in message.content:
if block.type == "tool_use" and block.name == "emit_alert_decision":
diff --git a/packages/core/openexecutive/api/routes/audit.py b/packages/core/openexecutive/api/routes/audit.py
index 634d9711..862fbcb6 100644
--- a/packages/core/openexecutive/api/routes/audit.py
+++ b/packages/core/openexecutive/api/routes/audit.py
@@ -100,6 +100,8 @@ class TokenCounts(BaseModel):
cache_read_input_tokens: int
cache_creation_input_tokens: int
output_tokens: int
+ # Server-side web searches the calls made (0 for rows that predate capture).
+ web_search_requests: int = 0
class TurnCost(TokenCounts):
@@ -130,15 +132,25 @@ class UsageByModel(UsageTotals):
model: str
+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
+ part of the system that produced it."""
+ source: str
+
+
class UsageSummary(BaseModel):
"""Aggregate token usage + cost across ALL sessions over an optional time
- window, with by-day and by-model breakdowns. Derived from `cache_event`
- rows — the same source as the per-session `CostSummary`, but unscoped."""
+ window, with by-day, by-model and by-source breakdowns. Derived from
+ `cache_event` rows — the same source as the per-session `CostSummary`,
+ but unscoped."""
since: str | None = None
until: str | None = None
totals: UsageTotals
by_day: list[UsageByDay]
by_model: list[UsageByModel]
+ by_source: list[UsageBySource] = []
class Degradation(BaseModel):
@@ -584,6 +596,7 @@ def get_audit_usage(
totals=UsageTotals(**data["totals"]),
by_day=[UsageByDay(**d) for d in data["by_day"]],
by_model=[UsageByModel(**m) for m in data["by_model"]],
+ by_source=[UsageBySource(**s) for s in data.get("by_source", [])],
)
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index 601ff4d1..0116d097 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -1333,7 +1333,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 Anthropic streaming response (per Executive iteration + the committee revision pass); captures `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `stop_reason` 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_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."
@@ -1341,7 +1341,7 @@ audit:
- external_signal_deferred — one row per poll that skipped entries whose published_at is more than the row's future-skew tolerance ahead (aggregated — `count`, `future_skew_hours`, `race_tick`, and up to 10 `entries` each with `dedup_key`, `published_at`, `summary` and `provenance_url`, so an operator can tell WHAT was held back). Emitted from the scan loop's finally, so it survives a poll that raises later in the same row. A deferred entry is by design NOT written to external_signals (that would burn its dedup key and mute it for good), so this row is its only trace until its date passes and it is judged normally.
- external_signal_promoted — one row per signal promoted into the alerts pipeline (post-suppression cascade). Carries `signal_id`, `watchlist_id`, `watchlist_slug`, `source_kind`, `severity_hint`, `dedup_key`, `provenance_url`. Pair with `external_signal_received` to compute promotion rate per watchlist row.
- external_monitor_poll — one row per watchlist row polled in a scan tick, emitted even when the row's poll raised or was cancelled (`failed` set to true, with `signals_emitted` still counting rows that landed before the failure, so the audit log stands on its own); `failed` is also true when the adapter crashed or no adapter is registered. A row with no registered adapter is still marked polled so it honours the cadence rather than re-firing every heartbeat. Carries `watchlist_id`, `watchlist_slug`, `signal_type`, `signals_emitted`, `duration_ms`, `failed`. Enables per-source health drill-down (`GET /audit?event_type=external_monitor_poll`) without needing a dedicated debug endpoint.
- - watchlist_research_periodic_ran — emitted by the periodic cron whenever the workflow actually fires. Carries `state_hash` (the input fingerprint at run time), `trigger` (`cold_start`, `state_changed`, or `staleness_floor`), `findings` count, `tool_calls` count, `ok_tool_calls`, `run_id`. The next tick reads the most recent row to decide skip-or-run (its `state_hash` for the fingerprint compare, its `ts` for the staleness floor). These three research run-history rows are the ONLY audit_log rows a fixture load/unload clears (via `monitoring.research.scheduler.clear_research_run_history`, called from `cli.fixture_loader._apply_state_from_source`): load wipes the profile/initiatives/watchlist that feed the fingerprint but otherwise preserves audit_log, so without this reset a same-fixture reload within the staleness floor would make the freshly-seeded scan skip itself and surface zero findings. A full reset still wipes all of audit_log.
+ - watchlist_research_periodic_ran — emitted by the periodic cron whenever the workflow actually fires. Carries `state_hash` (the input fingerprint at run time), `trigger` (`cold_start`, `state_changed`, or `staleness_floor`), `findings` count, `tool_calls` count, `ok_tool_calls`, `run_id`. The next tick reads the most recent row to decide skip-or-run (its `state_hash` for the fingerprint compare, its `ts` for the staleness floor). These three research run-history rows are the ONLY audit_log rows a fixture load/unload clears (via `monitoring.research.scheduler.clear_research_run_history`, called from `cli.fixture_loader._apply_state_from_source`): load wipes the profile/initiatives/watchlist that feed the fingerprint but otherwise preserves audit_log, so without this reset a same-fixture reload within the staleness floor would make the freshly-seeded scan skip itself and surface zero findings. A full reset still wipes all of audit_log. Also carries `usage` — the run's rollup of every model call it made (`calls`, token classes, `web_search_requests`, and `by_source` per actor), copied from the workflow's `result` event — so a run's weight is readable from the audit log."
- watchlist_research_periodic_skipped — emitted when the state_hash matches the last `_ran` row. Carries `state_hash`. Visible cost-saving signal in the audit log.
- watchlist_research_periodic_failed — emitted on workflow timeout / crash. Carries `state_hash` + `error` or `reason`.
- watchlist_research_added / watchlist_research_suggested / watchlist_research_rejected — one row per `propose_watch` the research watch policy decided (`monitoring.research.watch_policy`). Carries `slug`, `target`, `signal_type`, `rationale`, `entity`, `grounding_kind`, `score`, `reasons`, and for adds the quiet defaults applied (`cadence`, `severity_floor`, `trigger`). `_added` also renders in the brief's HANDLED block as `watching`.
@@ -1356,7 +1356,7 @@ audit:
ui_surfaces:
- /audit — filterable list with optional "Group by session" toggle, clickable session pills, and a per-group mini node-strip with "Open full view →" link
- /audit/session/[id] — three-pane flow-chart view (React Flow canvas + selected-node detail + collapsible JSON drawer)
- - /audit/usage — cross-session token-usage dashboard (totals cards incl. cost + cache-hit %, by-model and by-day tables with a UTC date-range filter); reached from the Settings hub (ADVANCED_ITEMS), not the primary nav
+ - /audit/usage — cross-session token-usage dashboard (totals cards incl. cost + cache-hit %, by-source, by-model and by-day tables with a UTC date-range filter; the by-source table groups on the row's `actor` and shows server-side searches); reached from the Settings hub (ADVANCED_ITEMS), not the primary nav
invariants:
- Audit is append-only — no UPDATE or DELETE paths from product code.
- summary is the searchable column (LIKE on indexed text), capped at ~300 chars; details_json carries opaque structured fields and is NOT searched.
diff --git a/packages/core/openexecutive/architecture/prebuilt/api.json b/packages/core/openexecutive/architecture/prebuilt/api.json
index 19599727..5c82055a 100644
--- a/packages/core/openexecutive/architecture/prebuilt/api.json
+++ b/packages/core/openexecutive/architecture/prebuilt/api.json
@@ -1,7 +1,7 @@
{
"section_id": "api",
"title": "API Reference",
- "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `talent` | `GET|POST|PATCH /engagements`, `GET|POST|PATCH /candidates`, `POST /candidates/{id}/stage`, `GET /engagements/{id}/matches`, `GET /candidates/{id}/similar`, `POST /talent/reindex`, `GET|POST|PATCH /offers`, `POST /offers/{id}/{extend,decision,archive}` | Executive-search pipeline: searches, candidates, semantic matching, and the offer lifecycle (extend/decision return the offer plus approval state, scheduled/cancelled expiry nudges, side effects, and warnings; lifecycle conflicts are 409s). |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats` | Knowledge review queue and annotations. |\n| `onboarding` | `/onboard/start`, `/onboard/answer` | Company-profile setup wizard. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Allowed sign-in emails. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",
+ "markdown": "The FastAPI surface lives in `openexecutive.api.main`, which mounts one router per topic. A shared-secret middleware gates every request via an `x-api-key` header, except `/health` and the `/webhook/*` callbacks (which carry their own verification). CORS is restricted to configured UI origins. The gate is off when `BACKEND_SHARED_SECRET` is unset — intended for local development only — so any internet-reachable deployment sets `OE_PUBLIC_DEPLOYMENT`, and `create_app()` then refuses to boot without the secret rather than serving an unauthenticated API.\n\nEndpoints grouped by router:\n\n| Router | Key endpoints | Purpose |\n|---|---|---|\n| `chat` | `POST /chat` | SSE stream of a live Executive turn. The request body optionally carries `page_context` (route, page title, guide section id, and a form descriptor with current values) — sent only by the Ask OE side panel so the Executive can explain the current page or propose form values. When the Executive calls its `propose_form_values` tool, the stream emits a `form_patch` event (`{type, form_id, fields, rationale, iteration}`) that the panel applies into the on-screen form as highlighted suggestions; the user reviews and saves through the form's normal submit path. |\n| `sessions` | `GET /sessions`, `GET /sessions/{id}/messages` | List and read saved chat sessions. |\n| `today` | `GET /today`, `GET /today/activity`, `GET /today/activity/daily` | Morning-brief aggregation, recent-action rail, and Pulse heartbeat heatmap (per-day activity counts). |\n| `people` | `GET\\|POST\\|PATCH /people`, `POST /people/{id}/archive` | Roster CRUD and scope lookups. |\n| `departments` | `GET\\|POST\\|PATCH\\|DELETE /departments`, `.../goals` | Department state and per-department goals. `PATCH /departments/{slug}` also takes `watched_entities` (≤50 names, `[]` clears) — the entities the research watch policy may add watches for and route to this department. |\n| `talent` | `GET|POST|PATCH /engagements`, `GET|POST|PATCH /candidates`, `POST /candidates/{id}/stage`, `GET /engagements/{id}/matches`, `GET /candidates/{id}/similar`, `POST /talent/reindex`, `GET|POST|PATCH /offers`, `POST /offers/{id}/{extend,decision,archive}` | Executive-search pipeline: searches, candidates, semantic matching, and the offer lifecycle (extend/decision return the offer plus approval state, scheduled/cancelled expiry nudges, side effects, and warnings; lifecycle conflicts are 409s). |\n| `agents` | `GET /agents`, `PATCH /agents/{id}`, `POST /agents/{id}/test` | Specialist metadata and Council overrides. |\n| `personas` | `GET\\|PUT\\|POST\\|DELETE /personas` | Executive persona definitions. |\n| `alerts` | `POST /alerts/{id}/ack`, `POST /alerts/bulk-ack`, `POST /alerts/{id}/reopen`, `POST /alerts/review` | Groom the briefing queue. `ack` (`read`/`ack`/`dismissed`, optional `mute_topic`) also teaches a watch-sourced alert's watch (`trust_score`); `bulk-ack` takes explicit `alert_ids` and/or `older_than_days` + `category` (exempt sources skipped); `reopen` is the Undo for a `resolved` / `expired` / `dismissed` alert (never `ack` or an artifact / decision row; back to `unread` with every review stamp cleared and its TTL anchor refreshed, so it is live again even if older than its TTL); `review` runs the Executive's relevance review on demand (ignores the interval; still honours `ALERT_REVIEW_ENABLED`, the per-pass caps, the single-flight lock and per-alert idempotency) and returns the move counts. `bulk-ack` caps ids at 500, needs `older_than_days >= 1`, and applies watch feedback per row; `mute_topic` must be one of the alert's tags or a scoped `external:` / `department:` pattern. Alerts still surface only through the briefing (`/today` reads the live view) — there is no list, prefs, mutes, or live-stream endpoint. |\n| `artifacts` | `GET /artifacts`, `POST /artifacts/{id}/archive` | Browsable research/document artifacts. |\n| `decisions` | `GET /decisions`, `POST /decisions/{id}/{approve,reject,cancel}`, `GET /audit/reliability` | Approval-gated decision instances (e.g. calendar bookings). A proposed booking is surfaced on the briefing as a companion alert; approve/reject/cancel here also clear that alert. Reviewed in the briefing — there is no separate proposals page. |\n| `audit` | `GET /audit/logs`, `GET /audit/logs/{id}`, `GET /audit/sessions/{id}`, `GET /audit/usage`, `POST /audit/log` | Durable audit trail of side effects. `/audit/sessions/{id}` adds a per-session token cost summary; `/audit/usage` aggregates token usage and OpenRouter cost across all sessions (totals, by day, by model, and by source — the part of the system that made the calls — including server-side web-search counts). |\n| `architecture` | `GET /architecture/sections`, `.../sections/{id}` | This documentation surface. |\n| `guide` | `GET /guide/sections`, `.../sections/{id}` | Plain-language user-guide content surface — mirrors `architecture` (static, version-controlled files; no LLM on the serving path). |\n| `health` | `GET /health`, `GET /health/honcho` | Liveness probes (unauthenticated). |\n| `documents` | `POST\\|GET\\|DELETE /documents`, `GET /documents/{filename}` | Upload, list, view extracted text, and delete indexed company docs. |\n| `scheduled` | `GET\\|DELETE` scheduled actions (`?status=…&order=asc\\|desc`) | Pending and fired scheduled actions; `order` flips the `run_at` sort (asc=soonest-first for the upcoming queue, desc=most-recent-first for terminal-status history). |\n| `watchlist` | `GET\\|POST\\|PATCH\\|DELETE /watchlist`, `POST /watchlist/{slug}/approve`, `POST /watchlist/{slug}/decline` | External-monitoring watchlist + signals. Rows carry `origin` (`manual` \\| `executive` \\| `research` \\| `research_proposed`); `approve` turns a research suggestion (`research_proposed`, `dry_run`) into a live watch, `decline` `{reason: not_relevant \\| too_noisy \\| wrong_source}` removes it and records the decline (or, for `too_noisy`, keeps it live at a high floor), both 409 unless the row is a pending suggestion; `DELETE ?reason=` on a research-origin row records the decline too. |\n| `workflows` | `GET /workflows`, `POST /workflows/{name}/runs`, `GET\\|POST\\|PUT\\|DELETE /workflows/custom` | Workflow catalog, run management, and user-created (dynamic) workflow CRUD. |\n| `knowledge` | `/knowledge/builtin`, `/external`, `/search` | MBA knowledge base and external sources. |\n| `skills` | `/skills`, `/skills/search` | Skill registry CRUD and search. |\n| `evals` | `/evals/scenarios`, `/evals/runs` | Eval scenarios and run results. |\n| `memories` | `/memories/{decisions,initiatives,advice}` | Episodic-memory record management. |\n| `review` | `/review/items`, `/review/stats` | Knowledge review queue and annotations. |\n| `onboarding` | `/onboard/start`, `/onboard/answer` | Company-profile setup wizard. |\n| `company-profile` | `GET\\|PATCH /company-profile` | Structured company profile. |\n| `auth` | `GET /auth/allowed-emails` | Allowed sign-in emails. |\n| `fixtures` | `/fixtures`, `/fixtures/{name}/load` | Demo-company fixture load/reset/snapshot. |\n| `clients` | `/clients`, `/clients/generate`, `/clients/cockpit`, `/clients/save`, `/clients/{slug}/activate` | Client-company slots — multi-client mode for fractional use; create from current/blank/AI-generated intake draft (pasted notes and/or file attachments, multipart on `/clients/generate`), save-back switching, engagement metadata (PATCH), cross-client cockpit, delete. See the Client Companies section. |\n| webhooks | `POST /webhook/telegram`, `POST /webhook/google-chat` | Inbound integration callbacks (self-verified). |\n| MCP server | `POST\\|GET /mcp` | Open Executive exposed as an MCP server (Streamable-HTTP). Not a router — a mounted FastMCP sub-app. Same shared-secret gate (`x-api-key`); exposes company context as resources and the specialist council as tools. See the MCP Server section. |",
"mermaid": null,
"generated_at": "2026-09-12T12:03:38.574978+00:00"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/audit.json b/packages/core/openexecutive/architecture/prebuilt/audit.json
index 1e7604eb..abd68249 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`, `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, 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/logger.py b/packages/core/openexecutive/audit/logger.py
index 96046c6f..6281566d 100644
--- a/packages/core/openexecutive/audit/logger.py
+++ b/packages/core/openexecutive/audit/logger.py
@@ -150,6 +150,7 @@ _USAGE_INT_FIELDS: tuple[str, ...] = (
"cache_read_input_tokens",
"cache_creation_input_tokens",
"output_tokens",
+ "web_search_requests",
)
@@ -175,6 +176,7 @@ _USAGE_SUM_COLS = """
SUM(COALESCE(CAST(json_extract(details_json,'$.cache_read_input_tokens') AS INTEGER),0)) AS cache_read_input_tokens,
SUM(COALESCE(CAST(json_extract(details_json,'$.cache_creation_input_tokens') AS INTEGER),0)) AS cache_creation_input_tokens,
SUM(COALESCE(CAST(json_extract(details_json,'$.output_tokens') AS INTEGER),0)) AS output_tokens,
+ SUM(COALESCE(CAST(json_extract(details_json,'$.web_search_requests') AS INTEGER),0)) AS web_search_requests,
SUM(COALESCE(CAST(json_extract(details_json,'$.cost_usd') AS REAL),0)) AS cost_usd
"""
@@ -431,7 +433,9 @@ class AuditLogger:
"""Aggregate token usage + cost from `cache_event` rows over an optional
time window. Grouping is done in SQL (`json_extract`) so this scales past
the 1000-row cap on `query()` — a busy DB can have far more cache_event
- rows than that. Returns totals plus by-day and by-model breakdowns.
+ rows than that. Returns totals plus by-day, by-model and by-source
+ breakdowns (source = the row's `actor`: executive, specialist_research,
+ research_synthesis, triage, …; rows without one group as `unknown`).
Each `cache_event` row carries the per-call token breakdown and (for
OpenRouter calls) the actual `cost_usd`; missing/garbled fields coalesce
@@ -439,7 +443,9 @@ class AuditLogger:
`until` bound the ISO `ts` column with the same string comparison used by
`query()`/`count()`.
"""
- empty: dict[str, Any] = {"totals": _zero_usage(), "by_day": [], "by_model": []}
+ empty: dict[str, Any] = {
+ "totals": _zero_usage(), "by_day": [], "by_model": [], "by_source": [],
+ }
if not self._db_path.exists():
return empty
@@ -469,11 +475,19 @@ class AuditLogger:
"GROUP BY model ORDER BY input_tokens DESC",
params,
).fetchall()
+ by_source_rows = conn.execute(
+ f"SELECT COALESCE(actor,'unknown') AS source, {_USAGE_SUM_COLS} "
+ f"FROM audit_log {where} GROUP BY source ORDER BY input_tokens DESC",
+ params,
+ ).fetchall()
return {
"totals": _row_to_usage(totals_row),
"by_day": [{"day": r["day"], **_row_to_usage(r)} for r in by_day_rows],
"by_model": [{"model": r["model"], **_row_to_usage(r)} for r in by_model_rows],
+ "by_source": [
+ {"source": r["source"], **_row_to_usage(r)} for r in by_source_rows
+ ],
}
diff --git a/packages/core/openexecutive/audit/usage.py b/packages/core/openexecutive/audit/usage.py
new file mode 100644
index 00000000..a980c4fd
--- /dev/null
+++ b/packages/core/openexecutive/audit/usage.py
@@ -0,0 +1,184 @@
+"""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
+: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
+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.
+"""
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Iterator
+from contextvars import ContextVar
+from typing import Any
+
+from openexecutive.audit.logger import log_event
+
+EVENT_TYPE = "cache_event"
+
+_research_run_id: ContextVar[str | None] = ContextVar("research_run_id", default=None)
+_research_rollup: ContextVar[UsageRollup | None] = ContextVar("research_rollup", default=None)
+
+
+def get_research_run_id() -> str | None:
+ """The research run the current task is part of, or ``None``."""
+ return _research_run_id.get()
+
+
+def bind_research_run(run_id: str | None) -> Iterator[UsageRollup]:
+ """Tag every usage row logged inside the block with ``run_id`` and sum
+ it into the yielded :class:`UsageRollup`. Tasks spawned inside the
+ block (the specialist fan-out) inherit the binding and share the same
+ rollup object, so their calls count too."""
+ rollup = UsageRollup()
+ token_id = _research_run_id.set(run_id)
+ token_rollup = _research_rollup.set(rollup)
+ try:
+ yield rollup
+ finally:
+ _research_rollup.reset(token_rollup)
+ _research_run_id.reset(token_id)
+
+
+def usage_counts(message: Any) -> dict[str, Any] | None:
+ """Read the token, cache, cost and web-search counters off a provider
+ ``Message`` (or the translator's SimpleNamespace). ``None`` when the
+ response carries no ``usage`` at all; every field is guarded so a
+ provider that omits one still yields the rest."""
+ usage = getattr(message, "usage", None)
+ if usage is None:
+ return None
+ raw_cost = getattr(usage, "cost", None)
+ try:
+ cost_usd = float(raw_cost) if raw_cost is not None else None
+ except (TypeError, ValueError):
+ cost_usd = None
+ server = getattr(usage, "server_tool_use", None)
+ return {
+ "input_tokens": _as_int(getattr(usage, "input_tokens", 0)),
+ "output_tokens": _as_int(getattr(usage, "output_tokens", 0)),
+ "cache_creation_input_tokens": _as_int(
+ getattr(usage, "cache_creation_input_tokens", 0)
+ ),
+ "cache_read_input_tokens": _as_int(getattr(usage, "cache_read_input_tokens", 0)),
+ "cost_usd": cost_usd,
+ "web_search_requests": _as_int(getattr(server, "web_search_requests", 0)),
+ }
+
+
+def log_model_usage(
+ message: Any,
+ *,
+ model: str,
+ actor: str,
+ iteration: int = 0,
+ session_id: str | None = None,
+ turn_id: str | None = None,
+) -> dict[str, Any] | None:
+ """Record one ``cache_event`` row for a completed model call.
+
+ Never raises and never touches the request: it reads ``message.usage``
+ after the call, so prompt caching is unaffected. Returns the counters it
+ recorded (``None`` when the response had no usage block). ``session_id``
+ / ``turn_id`` fall back to the audit ContextVars when omitted, as every
+ other audit row does.
+ """
+ counts = usage_counts(message)
+ if counts is None:
+ return None
+ rollup = _research_rollup.get()
+ if rollup is not None:
+ rollup.add(actor, counts)
+ stop_reason = getattr(message, "stop_reason", None)
+ details: dict[str, Any] = {
+ "model": model,
+ "iteration": iteration,
+ **counts,
+ "stop_reason": stop_reason,
+ }
+ run_id = get_research_run_id()
+ if run_id:
+ details["run_id"] = run_id
+ try:
+ log_event(
+ EVENT_TYPE,
+ (
+ f"{model} iter={iteration} in={counts['input_tokens']} "
+ f"out={counts['output_tokens']} "
+ f"cache_read={counts['cache_read_input_tokens']} "
+ f"cache_create={counts['cache_creation_input_tokens']} "
+ f"cost={counts['cost_usd']} "
+ f"searches={counts['web_search_requests']} stop={stop_reason}"
+ ),
+ session_id=session_id,
+ turn_id=turn_id,
+ actor=actor,
+ details=details,
+ )
+ except Exception: # noqa: BLE001 — audit is fire-and-forget
+ return counts
+ return counts
+
+
+class UsageRollup:
+ """Sums the counters of the calls one research run made, so the run's
+ result and audit row can say what it did (calls, tokens, searches)."""
+
+ _FIELDS = (
+ "input_tokens",
+ "cache_read_input_tokens",
+ "cache_creation_input_tokens",
+ "output_tokens",
+ "web_search_requests",
+ )
+
+ def __init__(self) -> None:
+ self.calls = 0
+ self.totals: dict[str, int] = dict.fromkeys(self._FIELDS, 0)
+ self.by_actor: dict[str, dict[str, int]] = {}
+
+ def add(self, actor: str, counts: dict[str, Any] | None) -> None:
+ if counts is None:
+ return
+ self.calls += 1
+ bucket = self.by_actor.setdefault(actor, {"calls": 0, **dict.fromkeys(self._FIELDS, 0)})
+ bucket["calls"] += 1
+ for field in self._FIELDS:
+ value = _as_int(counts.get(field, 0))
+ self.totals[field] += value
+ bucket[field] += value
+
+ def as_dict(self) -> dict[str, Any]:
+ return {
+ "calls": self.calls,
+ **self.totals,
+ "by_source": {k: dict(v) for k, v in sorted(self.by_actor.items())},
+ }
+
+
+def _as_int(value: Any) -> int:
+ try:
+ return int(value or 0)
+ except (TypeError, ValueError):
+ return 0
+
+
+__all__ = [
+ "EVENT_TYPE",
+ "UsageRollup",
+ "bind_research_run",
+ "get_research_run_id",
+ "log_model_usage",
+ "usage_counts",
+]
diff --git a/packages/core/openexecutive/memory/episodic.py b/packages/core/openexecutive/memory/episodic.py
index b6489f2f..7c673775 100644
--- a/packages/core/openexecutive/memory/episodic.py
+++ b/packages/core/openexecutive/memory/episodic.py
@@ -1776,6 +1776,7 @@ async def extract_and_store(
Runs as a background task — never blocks the response stream.
"""
try:
+ from openexecutive.audit.usage import log_model_usage
from openexecutive.config import get_settings
from openexecutive.providers import get_provider
@@ -1817,6 +1818,8 @@ async def extract_and_store(
],
)
+ log_model_usage(response, model=routing_model, actor="memory_extractor")
+
for block in response.content:
if block.type != "tool_use" or block.name != "store_memories":
continue
diff --git a/packages/core/openexecutive/monitoring/enrichment.py b/packages/core/openexecutive/monitoring/enrichment.py
index bde19f40..b70b4979 100644
--- a/packages/core/openexecutive/monitoring/enrichment.py
+++ b/packages/core/openexecutive/monitoring/enrichment.py
@@ -166,6 +166,7 @@ async def enrich_signal(
try:
message = await agent.analyze_with_tools(
user_content,
+ actor="signal_enrichment",
tools=[EMIT_RELEVANCE_TOOL],
timeout_seconds=_ENRICH_TIMEOUT_SECONDS,
model_override=get_research_model(),
diff --git a/packages/core/openexecutive/monitoring/research/scheduler.py b/packages/core/openexecutive/monitoring/research/scheduler.py
index 3f41942d..7ef5b8b3 100644
--- a/packages/core/openexecutive/monitoring/research/scheduler.py
+++ b/packages/core/openexecutive/monitoring/research/scheduler.py
@@ -484,9 +484,10 @@ async def run_watchlist_research_scan(
artifact = ""
findings: list[dict[str, Any]] = []
tool_calls: list[dict[str, Any]] = []
+ usage: dict[str, Any] | None = None
async def _drive() -> None:
- nonlocal artifact, findings, tool_calls
+ nonlocal artifact, findings, tool_calls, usage
async for event in workflow.run(
inputs=wf_inputs, store=effective_store,
):
@@ -497,6 +498,9 @@ async def run_watchlist_research_scan(
raw_calls = event.data.get("tool_calls")
if isinstance(raw_calls, list):
tool_calls = raw_calls
+ raw_usage = event.data.get("usage")
+ if isinstance(raw_usage, dict):
+ usage = raw_usage
elif event.type == "artifact" and event.content:
artifact = event.content
elif event.type == "error" and event.message:
@@ -531,21 +535,31 @@ async def run_watchlist_research_scan(
# next tick — bounded, not lost.
post_state_hash = compute_research_state_hash(db_path=db_path)
ok_tool_calls = sum(1 for t in tool_calls if t.get("ok"))
+ usage_note = ""
+ if usage:
+ usage_note = (
+ f", {usage.get('calls', 0)} model call(s), "
+ f"{usage.get('web_search_requests', 0)} search(es)"
+ )
+ details: dict[str, Any] = {
+ "state_hash": post_state_hash,
+ "trigger": run_trigger,
+ "findings": len(findings),
+ "tool_calls": len(tool_calls),
+ "ok_tool_calls": ok_tool_calls,
+ "run_id": run_id,
+ }
+ if usage:
+ # What the run did: calls, tokens and searches, per source.
+ details["usage"] = usage
audit_log(
EVENT_RAN,
(
f"Executive research ran — {len(findings)} finding(s), "
- f"{ok_tool_calls}/{len(tool_calls)} tool call(s) ok"
+ f"{ok_tool_calls}/{len(tool_calls)} tool call(s) ok{usage_note}"
),
actor="scheduler",
- details={
- "state_hash": post_state_hash,
- "trigger": run_trigger,
- "findings": len(findings),
- "tool_calls": len(tool_calls),
- "ok_tool_calls": ok_tool_calls,
- "run_id": run_id,
- },
+ details=details,
)
return len(findings)
except TimeoutError:
diff --git a/packages/core/openexecutive/monitoring/research/specialist_research.py b/packages/core/openexecutive/monitoring/research/specialist_research.py
index 5128ee0a..55872cef 100644
--- a/packages/core/openexecutive/monitoring/research/specialist_research.py
+++ b/packages/core/openexecutive/monitoring/research/specialist_research.py
@@ -65,6 +65,7 @@ async def research_one_specialist(
try:
message = await agent.analyze_with_tools(
research_context,
+ actor="specialist_research",
tools=tools,
system_addendum=research_addendum_for(specialist_slug),
timeout_seconds=_RESEARCH_TIMEOUT_SECONDS,
diff --git a/packages/core/openexecutive/monitoring/sources/query.py b/packages/core/openexecutive/monitoring/sources/query.py
index 0c2b27df..ac714d69 100644
--- a/packages/core/openexecutive/monitoring/sources/query.py
+++ b/packages/core/openexecutive/monitoring/sources/query.py
@@ -188,6 +188,7 @@ class QuerySource:
try:
message = await agent.analyze_with_tools(
user_content,
+ actor="query_watch",
tools=tools,
timeout_seconds=_QUERY_TIMEOUT_SECONDS,
model_override=get_research_model(),
diff --git a/packages/core/openexecutive/orchestrator/executive.py b/packages/core/openexecutive/orchestrator/executive.py
index aa5bee3b..1d12f54b 100644
--- a/packages/core/openexecutive/orchestrator/executive.py
+++ b/packages/core/openexecutive/orchestrator/executive.py
@@ -17,6 +17,7 @@ from openexecutive.audit.redaction import (
audit_tool_result,
audit_tool_result_full,
)
+from openexecutive.audit.usage import log_model_usage
from openexecutive.config import get_settings
from openexecutive.memory.honcho_client import ReasoningLevel as HonchoReasoningLevel
from openexecutive.orchestrator.action_chips import summarize_action
@@ -322,45 +323,17 @@ def _emit_cache_event(
model: str,
actor: str = "executive",
) -> None:
- """Capture token + cache stats from an Anthropic streaming response.
-
- Reads from `final_msg.usage` (a SimpleNamespace from the provider
- abstraction in providers/translator.py). All getattrs are guarded so
- a provider that doesn't surface a particular field still emits a row
- with what it does have — never blocks the caller.
- """
- usage = getattr(final_msg, "usage", None)
- if usage is None:
- return
- inp = int(getattr(usage, "input_tokens", 0) or 0)
- out = int(getattr(usage, "output_tokens", 0) or 0)
- cache_create = int(getattr(usage, "cache_creation_input_tokens", 0) or 0)
- cache_read = int(getattr(usage, "cache_read_input_tokens", 0) or 0)
- stop_reason = getattr(final_msg, "stop_reason", None)
- # Actual USD charged for this call, surfaced by OpenRouter when usage
- # accounting is enabled. None on the Anthropic-direct path (no cost wire);
- # stored as-is so aggregation treats a missing cost as 0.
- raw_cost = getattr(usage, "cost", None)
- try:
- cost_usd = float(raw_cost) if raw_cost is not None else None
- except (TypeError, ValueError):
- cost_usd = None
- audit_log(
- "cache_event",
- f"{model} iter={iteration} in={inp} out={out} cache_read={cache_read} cache_create={cache_create} cost={cost_usd} stop={stop_reason}",
+ """Record the token + cache stats of one Executive response as a
+ ``cache_event`` row (see ``audit.usage.log_model_usage``, which every
+ other model call site uses too). Reads ``final_msg.usage`` after the
+ call, never touches the request, never raises."""
+ log_model_usage(
+ final_msg,
+ model=model,
+ actor=actor,
+ iteration=iteration,
session_id=session_id,
turn_id=turn_id,
- actor=actor,
- details={
- "model": model,
- "iteration": iteration,
- "input_tokens": inp,
- "output_tokens": out,
- "cache_creation_input_tokens": cache_create,
- "cache_read_input_tokens": cache_read,
- "cost_usd": cost_usd,
- "stop_reason": stop_reason,
- },
)
diff --git a/packages/core/openexecutive/workflows/executive_research.py b/packages/core/openexecutive/workflows/executive_research.py
index ee8d4ece..22590420 100644
--- a/packages/core/openexecutive/workflows/executive_research.py
+++ b/packages/core/openexecutive/workflows/executive_research.py
@@ -40,11 +40,13 @@ from __future__ import annotations
import asyncio
import logging
+import uuid
from collections.abc import AsyncIterator
from typing import Any
from pydantic import BaseModel, Field
+from openexecutive.audit.usage import UsageRollup, bind_research_run, log_model_usage
from openexecutive.knowledge.store import ChromaDBStore
from openexecutive.monitoring.research.dedup import dedup_findings
from openexecutive.monitoring.research.models import (
@@ -381,7 +383,19 @@ class ExecutiveResearchWorkflow(Workflow):
store: ChromaDBStore,
) -> AsyncIterator[WorkflowEvent]:
assert isinstance(inputs, ExecutiveResearchInput)
-
+ # Every model call the run makes (specialists, synthesis, watchlist
+ # pass) records a cache_event row tagged with this id and summed into
+ # the rollup, which the result event reports as `usage`.
+ with bind_research_run(f"research-{uuid.uuid4().hex[:12]}") as rollup:
+ async for event in self._run_events(inputs, store, rollup):
+ yield event
+
+ async def _run_events(
+ self,
+ inputs: ExecutiveResearchInput,
+ store: ChromaDBStore,
+ rollup: UsageRollup,
+ ) -> AsyncIterator[WorkflowEvent]:
# ------------------------------------------------------------------
# Step 1: gather_context
# ------------------------------------------------------------------
@@ -553,7 +567,10 @@ class ExecutiveResearchWorkflow(Workflow):
if not deduped:
yield WorkflowEvent(
type="result",
- data={"findings": [], "tool_calls": [], "narrative": ""},
+ data={
+ "findings": [], "tool_calls": [], "narrative": "",
+ "usage": rollup.as_dict(),
+ },
)
yield WorkflowEvent(
type="artifact",
@@ -678,6 +695,7 @@ class ExecutiveResearchWorkflow(Workflow):
],
"tool_calls": tool_calls,
"narrative": narrative,
+ "usage": rollup.as_dict(),
},
)
yield WorkflowEvent(type="artifact", content=artifact)
@@ -796,6 +814,9 @@ async def _executive_synthesis_loop(
iteration,
)
break
+ log_model_usage(
+ response, model=model, actor="research_synthesis", iteration=iteration,
+ )
ok_so_far = _routing_ok(tool_calls)
budget_remaining = max(0, _MAX_ROUTING_TOOLS_PER_RUN - ok_so_far)
@@ -972,6 +993,9 @@ async def _watchlist_analysis_loop(
except Exception:
logger.exception("research.watchlist: provider call failed")
break
+ log_model_usage(
+ response, model=model, actor="research_watchlist", iteration=_iteration,
+ )
budget_remaining = max(0, _MAX_WATCHLIST_PROPOSALS_PER_RUN - len(proposals))
iter_calls = await execute_tool_calls(
diff --git a/packages/core/tests/unit/test_audit_logger.py b/packages/core/tests/unit/test_audit_logger.py
index 4ecbb933..5754cf19 100644
--- a/packages/core/tests/unit/test_audit_logger.py
+++ b/packages/core/tests/unit/test_audit_logger.py
@@ -233,10 +233,32 @@ def test_usage_summary_empty_db_returns_zeros(tmp_path: Path) -> None:
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 0,
+ "web_search_requests": 0,
"cost_usd": 0.0,
}
assert s["by_day"] == []
assert s["by_model"] == []
+ assert s["by_source"] == []
+
+
+def test_usage_summary_groups_by_source_and_sums_searches(audit: AuditLogger) -> None:
+ audit.log("cache_event", "chat", actor="executive",
+ details={"model": "m", "input_tokens": 100, "web_search_requests": 1})
+ audit.log("cache_event", "research 1", actor="specialist_research",
+ details={"model": "m", "input_tokens": 40, "web_search_requests": 3})
+ audit.log("cache_event", "research 2", actor="specialist_research",
+ details={"model": "m", "input_tokens": 60, "web_search_requests": 2})
+ audit.log("cache_event", "legacy row, no actor",
+ details={"model": "m", "input_tokens": 5})
+
+ s = audit.usage_summary()
+ assert s["totals"]["web_search_requests"] == 6
+ by_source = {r["source"]: r for r in s["by_source"]}
+ assert set(by_source) == {"executive", "specialist_research", "unknown"}
+ assert by_source["specialist_research"]["calls"] == 2
+ assert by_source["specialist_research"]["input_tokens"] == 100
+ assert by_source["specialist_research"]["web_search_requests"] == 5
+ assert by_source["unknown"]["input_tokens"] == 5
def test_usage_summary_aggregates_across_sessions_and_models(audit: AuditLogger) -> None:
diff --git a/packages/core/tests/unit/test_audit_route.py b/packages/core/tests/unit/test_audit_route.py
index 52fa1e32..6c7c6c16 100644
--- a/packages/core/tests/unit/test_audit_route.py
+++ b/packages/core/tests/unit/test_audit_route.py
@@ -239,6 +239,21 @@ def test_usage_endpoint_aggregates_across_sessions(tmp_path: Path) -> None:
assert by_model["claude-opus-4-8"]["cost_usd"] == pytest.approx(0.05)
+def test_usage_endpoint_breaks_down_by_source(tmp_path: Path) -> None:
+ client = _session_client(tmp_path)
+ audit = client.app.state.audit # type: ignore[attr-defined]
+ audit.log("cache_event", "chat", session_id="sA", turn_id="t1", actor="executive",
+ details={"model": "m", "input_tokens": 100, "web_search_requests": 1})
+ audit.log("cache_event", "research", actor="specialist_research",
+ details={"model": "m", "input_tokens": 40, "web_search_requests": 4})
+
+ data = client.get("/audit/usage").json()
+ assert data["totals"]["web_search_requests"] == 5
+ by_source = {s["source"]: s for s in data["by_source"]}
+ assert by_source["executive"]["calls"] == 1
+ assert by_source["specialist_research"]["web_search_requests"] == 4
+
+
def test_usage_endpoint_cost_missing_rows_contribute_zero(tmp_path: Path) -> None:
# A row predating cost capture (no cost_usd) must not break the sum.
client = _session_client(tmp_path)
diff --git a/packages/core/tests/unit/test_audit_usage.py b/packages/core/tests/unit/test_audit_usage.py
new file mode 100644
index 00000000..abc66623
--- /dev/null
+++ b/packages/core/tests/unit/test_audit_usage.py
@@ -0,0 +1,116 @@
+"""Unit tests for per-call model usage recording (audit.usage)."""
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from openexecutive.audit import usage as au
+from openexecutive.audit.logger import AuditLogger, set_audit_logger
+
+
+def audit(tmp_path: Path) -> AuditLogger:
+ logger = AuditLogger(tmp_path / "audit.db")
+ set_audit_logger(logger)
+ yield logger # type: ignore[misc]
+ set_audit_logger(None)
+
+
+def _message(**usage: object) -> SimpleNamespace:
+ return SimpleNamespace(usage=SimpleNamespace(**usage), stop_reason="end_turn")
+
+
+def test_usage_counts_reads_tokens_cost_and_server_searches() -> None:
+ msg = _message(
+ input_tokens=120, output_tokens=30, cache_creation_input_tokens=10,
+ cache_read_input_tokens=900, cost="0.04",
+ server_tool_use=SimpleNamespace(web_search_requests=3),
+ )
+ counts = au.usage_counts(msg)
+ assert counts == {
+ "input_tokens": 120, "output_tokens": 30,
+ "cache_creation_input_tokens": 10, "cache_read_input_tokens": 900,
+ "cost_usd": 0.04, "web_search_requests": 3,
+ }
+
+
+def test_usage_counts_tolerates_missing_fields_and_no_usage() -> None:
+ assert au.usage_counts(SimpleNamespace(content=[])) is None
+ counts = au.usage_counts(_message(input_tokens=5, cost="not-a-number"))
+ assert counts is not None
+ assert counts["output_tokens"] == 0 and counts["web_search_requests"] == 0
+ assert counts["cost_usd"] is None
+
+
+def test_log_model_usage_writes_one_cache_event_row(audit: AuditLogger) -> None:
+ msg = _message(input_tokens=50, output_tokens=7,
+ server_tool_use=SimpleNamespace(web_search_requests=2))
+ counts = au.log_model_usage(msg, model="claude-sonnet-5", actor="specialist_research",
+ iteration=1, session_id="s1", turn_id="t1")
+ assert counts is not None and counts["web_search_requests"] == 2
+ rows = audit.query(event_type="cache_event")
+ assert len(rows) == 1
+ row = rows[0]
+ assert row.actor == "specialist_research" and row.session_id == "s1"
+ assert row.details["model"] == "claude-sonnet-5"
+ assert row.details["input_tokens"] == 50 and row.details["web_search_requests"] == 2
+ assert "run_id" not in row.details
+
+
+def test_log_model_usage_tags_rows_with_the_bound_research_run(audit: AuditLogger) -> None:
+ with au.bind_research_run("run-abc") as rollup:
+ assert au.get_research_run_id() == "run-abc"
+ au.log_model_usage(_message(input_tokens=1), model="m", actor="research_synthesis")
+ au.log_model_usage(
+ _message(input_tokens=4, server_tool_use=SimpleNamespace(web_search_requests=2)),
+ model="m", actor="specialist_research",
+ )
+ assert au.get_research_run_id() is None
+ # The bound rollup summed both calls; a call outside the block does not count.
+ au.log_model_usage(_message(input_tokens=100), model="m", actor="executive")
+ out = rollup.as_dict()
+ assert out["calls"] == 2 and out["input_tokens"] == 5 and out["web_search_requests"] == 2
+ assert set(out["by_source"]) == {"research_synthesis", "specialist_research"}
+ au.log_model_usage(_message(input_tokens=1), model="m", actor="executive")
+ rows = {r.actor: r for r in audit.query(event_type="cache_event")}
+ assert rows["research_synthesis"].details["run_id"] == "run-abc"
+ assert rows["specialist_research"].details["run_id"] == "run-abc"
+ assert "run_id" not in rows["executive"].details
+
+
+async def test_rollup_collects_calls_made_in_gathered_tasks(audit: AuditLogger) -> None:
+ """The specialist fan-out runs in asyncio.gather sub-tasks; they inherit
+ the binding and share the rollup object."""
+ import asyncio
+
+ async def one_call(i: int) -> None:
+ au.log_model_usage(_message(input_tokens=i), model="m", actor="specialist_research")
+
+ with au.bind_research_run("run-gather") as rollup:
+ await asyncio.gather(one_call(1), one_call(2), one_call(3))
+ assert rollup.as_dict()["calls"] == 3 and rollup.as_dict()["input_tokens"] == 6
+
+
+def test_log_model_usage_returns_none_without_usage(audit: AuditLogger) -> None:
+ assert au.log_model_usage(SimpleNamespace(content=[]), model="m", actor="triage") is None
+ assert audit.query(event_type="cache_event") == []
+
+
+def test_usage_rollup_sums_per_source() -> None:
+ roll = au.UsageRollup()
+ roll.add("specialist_research", {"input_tokens": 10, "output_tokens": 2, "web_search_requests": 3})
+ roll.add("specialist_research", {"input_tokens": 5, "output_tokens": 1, "web_search_requests": 1})
+ roll.add("research_synthesis", {"input_tokens": 7, "cache_read_input_tokens": 100})
+ roll.add("research_watchlist", None) # a call without usage is not counted
+ out = roll.as_dict()
+ assert out["calls"] == 3
+ assert out["input_tokens"] == 22 and out["web_search_requests"] == 4
+ assert out["cache_read_input_tokens"] == 100
+ assert out["by_source"]["specialist_research"] == {
+ "calls": 2, "input_tokens": 15, "cache_read_input_tokens": 0,
+ "cache_creation_input_tokens": 0, "output_tokens": 3, "web_search_requests": 4,
+ }
+ assert list(out["by_source"]) == ["research_synthesis", "specialist_research"]
diff --git a/packages/core/tests/unit/test_executive_research_scheduler.py b/packages/core/tests/unit/test_executive_research_scheduler.py
index 2f1ecd27..8fd7c637 100644
--- a/packages/core/tests/unit/test_executive_research_scheduler.py
+++ b/packages/core/tests/unit/test_executive_research_scheduler.py
@@ -180,6 +180,42 @@ def _make_workflow_stub(
return workflow
+async def test_scan_audit_row_carries_the_runs_usage(
+ db: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """The workflow's `usage` rollup lands on the `_ran` audit row so a run's
+ weight can be read from the audit log."""
+ usage = {
+ "calls": 9, "input_tokens": 1200, "cache_read_input_tokens": 300,
+ "cache_creation_input_tokens": 0, "output_tokens": 400, "web_search_requests": 14,
+ "by_source": {"specialist_research": {"calls": 7, "web_search_requests": 14}},
+ }
+
+ async def fake_run(*, inputs, store):
+ from openexecutive.workflows.base import WorkflowEvent
+ yield WorkflowEvent(
+ type="result", data={"findings": [], "tool_calls": [], "usage": usage},
+ )
+ yield WorkflowEvent(type="artifact", content="(empty)")
+ yield WorkflowEvent(type="done")
+
+ workflow = MagicMock()
+ workflow.run = fake_run
+ workflow.input_model.return_value = _MinimalInput
+ workflow.title = "Executive Research"
+ monkeypatch.setitem(
+ __import__("openexecutive.workflows", fromlist=["WORKFLOW_REGISTRY"]).WORKFLOW_REGISTRY,
+ "executive_research", workflow,
+ )
+ await research_scheduler.run_watchlist_research_scan(db_path=db, store=MagicMock())
+
+ from openexecutive.audit import get_audit_logger
+ ran = get_audit_logger().query(event_type=research_scheduler.EVENT_RAN, limit=1)
+ assert (ran[0].details or {}).get("usage") == usage
+ assert "9 model call(s), 14 search(es)" in ran[0].summary
+
+
@pytest.mark.asyncio
async def test_scan_skips_when_state_unchanged(
db: Path, monkeypatch: pytest.MonkeyPatch,
diff --git a/packages/core/tests/unit/test_executive_research_workflow.py b/packages/core/tests/unit/test_executive_research_workflow.py
index 478124b7..c3fbc18c 100644
--- a/packages/core/tests/unit/test_executive_research_workflow.py
+++ b/packages/core/tests/unit/test_executive_research_workflow.py
@@ -306,6 +306,9 @@ async def test_workflow_runs_end_to_end_with_stubbed_specialists(
assert "cfo" in result_data["findings"][0]["source_specialist"]
assert len(result_data["tool_calls"]) == 1
assert result_data["tool_calls"][0]["tool"] == "send_slack_dm"
+ # The run reports what it did; the stubs made no model calls.
+ assert result_data["usage"]["calls"] == 0
+ assert result_data["usage"]["by_source"] == {}
@pytest.mark.asyncio
diff --git a/packages/core/tests/unit/test_usage_recording.py b/packages/core/tests/unit/test_usage_recording.py
new file mode 100644
index 00000000..3507d42b
--- /dev/null
+++ b/packages/core/tests/unit/test_usage_recording.py
@@ -0,0 +1,98 @@
+"""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)."""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openexecutive.agents.base import BaseAgent
+from openexecutive.audit.logger import AuditLogger, set_audit_logger
+
+
+def audit(tmp_path: Path) -> AuditLogger:
+ logger = AuditLogger(tmp_path / "audit.db")
+ set_audit_logger(logger)
+ yield logger # type: ignore[misc]
+ set_audit_logger(None)
+
+
+def _response(**usage: object) -> SimpleNamespace:
+ return SimpleNamespace(
+ content=[], stop_reason="end_turn", usage=SimpleNamespace(**usage),
+ )
+
+
+class _Agent(BaseAgent):
+ name = "unit_agent"
+ domain = "unit"
+ model = "claude-test"
+
+ def get_system_prompt(self) -> str:
+ return "prompt"
+
+
+def test_analyze_with_tools_records_usage_under_the_callers_actor(
+ audit: AuditLogger, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr("openexecutive.agents.overrides.get_override", lambda _name: None)
+ provider = SimpleNamespace(messages_create=AsyncMock(return_value=_response(
+ input_tokens=70, output_tokens=9,
+ server_tool_use=SimpleNamespace(web_search_requests=3),
+ )))
+ monkeypatch.setattr("openexecutive.agents.base.get_provider", lambda _m: provider)
+
+ asyncio.run(_Agent().analyze_with_tools(
+ "ctx", tools=[{"name": "t", "input_schema": {"type": "object"}}],
+ model_override="claude-research", actor="specialist_research",
+ ))
+ rows = audit.query(event_type="cache_event")
+ assert len(rows) == 1
+ assert rows[0].actor == "specialist_research"
+ assert rows[0].details["model"] == "claude-research"
+ assert rows[0].details["web_search_requests"] == 3
+
+
+def test_triage_records_usage(audit: AuditLogger) -> None:
+ from openexecutive.agents.triage import TriageAgent
+ from openexecutive.alerts.models import AlertEvent
+
+ block = SimpleNamespace(type="tool_use", name="emit_alert_decision", input={
+ "alert": False, "severity": "low", "channels": ["persisted"], "headline": "h",
+ "body": "b", "suggested_action": "", "topic_tags": [], "dedup_key": "k",
+ "reason_if_suppressed": "noise",
+ })
+ response = SimpleNamespace(content=[block], stop_reason="tool_use",
+ usage=SimpleNamespace(input_tokens=33, output_tokens=5))
+ client = SimpleNamespace(messages=SimpleNamespace(create=AsyncMock(return_value=response)))
+ asyncio.run(TriageAgent().triage(
+ AlertEvent(source="email", external_id="m1", subject="s", body="b"), client=client,
+ ))
+ rows = audit.query(event_type="cache_event")
+ assert len(rows) == 1 and rows[0].actor == "triage"
+ assert rows[0].details["input_tokens"] == 33
+
+
+def test_memory_extractor_records_usage(
+ audit: AuditLogger, tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ from openexecutive.memory import episodic as ep
+
+ db = tmp_path / "episodic.db"
+ ep.initialize_db(db)
+ provider = SimpleNamespace(messages_create=AsyncMock(return_value=_response(
+ input_tokens=12, output_tokens=2,
+ )))
+ monkeypatch.setattr("openexecutive.providers.get_provider", lambda _m: provider)
+ monkeypatch.setattr(
+ "openexecutive.config.get_settings", lambda: SimpleNamespace(routing_model="claude-test"),
+ )
+ asyncio.run(ep.extract_and_store("user message", "assistant response", db_path=db))
+ rows = audit.query(event_type="cache_event")
+ assert len(rows) == 1 and rows[0].actor == "memory_extractor"
+ assert rows[0].details["model"] == "claude-test"
diff --git a/packages/ui/src/app/audit/usage/page.tsx b/packages/ui/src/app/audit/usage/page.tsx
index ad192151..17562130 100644
--- a/packages/ui/src/app/audit/usage/page.tsx
+++ b/packages/ui/src/app/audit/usage/page.tsx
@@ -6,6 +6,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import {
getAuditUsage,
type UsageByDay,
+ type UsageBySource,
type UsageByModel,
type UsageSummary,
type UsageTotals,
@@ -188,6 +189,38 @@ export default function TokenUsagePage() {
</div>
) : null}
+ {/* By source */}
+ {data && data.by_source && data.by_source.length > 0 ? (
+ <section className="mt-8">
+ <h2 className="text-sm font-medium text-fg mb-2">By source</h2>
+ <p className="text-xs text-fg-muted mb-2">
+ Which part of the system made the calls: chat turns, research specialists, the research routing and watchlist passes, triage, memory extraction.
+ </p>
+ <div className="rounded-xl border border-line overflow-hidden">
+ <table className="w-full text-sm">
+ <thead>
+ <tr className="bg-surface-elevated/60 text-fg-muted text-xs">
+ <th className="px-3 py-2 text-left font-medium">Source</th>
+ <th className="px-3 py-2 text-right font-medium">Searches</th>
+ {COL_HEADERS.map((h) => (
+ <th key={h} className="px-3 py-2 text-right font-medium">{h}</th>
+ ))}
+ </tr>
+ </thead>
+ <tbody>
+ {data.by_source.map((s: UsageBySource) => (
+ <tr key={s.source} className="border-t border-line/60">
+ <td className="px-3 py-1.5 font-mono text-xs text-fg">{s.source}</td>
+ <td className="px-3 py-1.5 text-right tabular-nums">{fmtInt(s.web_search_requests ?? 0)}</td>
+ <UsageRowCells u={s} />
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ </section>
+ ) : null}
+
{/* By model */}
{data && data.by_model.length > 0 ? (
<section className="mt-8">
diff --git a/packages/ui/src/lib/api.ts b/packages/ui/src/lib/api.ts
index b6773691..37db0cf9 100644
--- a/packages/ui/src/lib/api.ts
+++ b/packages/ui/src/lib/api.ts
@@ -1606,9 +1606,10 @@ export async function getAuditSession(
return res.json();
}
-// Cross-session token-usage aggregate used by /audit/usage. Totals plus by-day
-// and by-model breakdowns, summed from cache_event rows. `cost_usd` is the
-// actual OpenRouter charge captured per call (0 for rows that predate capture).
+// Cross-session token-usage aggregate used by /audit/usage. Totals plus by-day,
+// by-model and by-source breakdowns, summed from cache_event rows. `cost_usd` is
+// the actual OpenRouter charge captured per call (0 for rows that predate
+// capture); `web_search_requests` counts server-side searches the calls made.
export interface UsageTotals {
calls: number;
@@ -1616,6 +1617,7 @@ export interface UsageTotals {
cache_read_input_tokens: number;
cache_creation_input_tokens: number;
output_tokens: number;
+ web_search_requests: number;
cost_usd: number;
}
@@ -1627,12 +1629,19 @@ 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, …
+export interface UsageBySource extends UsageTotals {
+ source: string;
+}
+
export interface UsageSummary {
since: string | null;
until: string | null;
totals: UsageTotals;
by_day: UsageByDay[];
by_model: UsageByModel[];
+ by_source: UsageBySource[];
}
export async function getAuditUsage(