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.mdindex 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.0routing pass can no longer start a workflow (`run_workflow` is withheld,`suggest_workflow` remains); the periodic run's default interval movesfrom 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.** Thediff --git a/packages/core/openexecutive/agents/base.py b/packages/core/openexecutive/agents/base.pyindex ba834cd1..82628e5e 100644--- a/packages/core/openexecutive/agents/base.py+++ b/packages/core/openexecutive/agents/base.py@@ -4,6 +4,7 @@ import loggingfrom abc import ABC, abstractmethodfrom typing import Any+from openexecutive.audit.usage import log_model_usagefrom openexecutive.config import get_settingsfrom 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. WhenNone, the per-instance effective_* values apply, matching priorbehavior.++ ``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 messagediff --git a/packages/core/openexecutive/agents/triage.py b/packages/core/openexecutive/agents/triage.pyindex 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_usagefrom openexecutive.providers import get_providerif 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.pyindex 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: intcache_creation_input_tokens: intoutput_tokens: int+ # Server-side web searches the calls made (0 for rows that predate capture).+ web_search_requests: int = 0class 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 = Noneuntil: str | None = Nonetotals: UsageTotalsby_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.yamlindex 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 navinvariants:- 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.jsonindex 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.jsonindex 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.pyindex 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 optionaltime window. Grouping is done in SQL (`json_extract`) so this scales pastthe 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 (forOpenRouter 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.pynew file mode 100644index 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.pyindex 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_usagefrom openexecutive.config import get_settingsfrom 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":continuediff --git a/packages/core/openexecutive/monitoring/enrichment.py b/packages/core/openexecutive/monitoring/enrichment.pyindex 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.pyindex 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 = Noneasync def _drive() -> None:- nonlocal artifact, findings, tool_calls+ nonlocal artifact, findings, tool_calls, usageasync 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_usageelif event.type == "artifact" and event.content:artifact = event.contentelif 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"] = usageaudit_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.pyindex 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.pyindex 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.pyindex 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_usagefrom openexecutive.config import get_settingsfrom openexecutive.memory.honcho_client import ReasoningLevel as HonchoReasoningLevelfrom 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.pyindex 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 annotationsimport asyncioimport logging+import uuidfrom collections.abc import AsyncIteratorfrom typing import Anyfrom pydantic import BaseModel, Field+from openexecutive.audit.usage import UsageRollup, bind_research_run, log_model_usagefrom openexecutive.knowledge.store import ChromaDBStorefrom openexecutive.monitoring.research.dedup import dedup_findingsfrom 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.pyindex 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"] == 5def 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.pyindex 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.pynew file mode 100644index 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.pyindex 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.asyncioasync 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.pyindex 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"]) == 1assert 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.asynciodiff --git a/packages/core/tests/unit/test_usage_recording.py b/packages/core/tests/unit/test_usage_recording.pynew file mode 100644index 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.tsxindex 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.tsindex 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(