Skip to content

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

29.5 KB
Raw Blame
"""Read API for the audit log.

Filter by event type, session, actor, date range, plus a LIKE search on the
human-readable `summary` column. Pagination is offset-based.

Also exposes a session-scoped read at GET /audit/sessions/{session_id} that
returns the full ordered timeline for one inbound request plus a derived
graph (nodes + edges) so the UI can render a flow-chart view without
re-deriving causality from event types client-side.

Rows private to the principal (``AuditEvent.private`` — see
``audit.logger``) are read by the principal alone: every read route leaves
them out for anyone else, in SQL, so totals and pages stay honest, and a
private row's id answers 404 exactly like a missing one. A team member's own
rows (``AuditEvent.private_to_person``: their own chats with the Executive,
their mail, Act as me) are theirs: nobody else reads their words.

Once a principal is on the roster, anyone else reads their own rows and
nothing more (``_view``): the log holds what everyone said to the Executive,
so it isn't a shared page. The principal reads a team member's own rows as
actions only (``_redact``): what was done, when and in whose conversation,
never what was said, and a text search leaves them out.
"""
from __future__ import annotations

import logging
import re
from typing import Any

from fastapi import APIRouter, HTTPException, Query, Request
from pydantic import BaseModel

from openexecutive.api import path_ids  # noqa: F401  (registers the {…:session} convertor)
from openexecutive.audit import AuditLogger, get_audit_logger
from openexecutive.audit.logger import EVENT_TYPES

# Session IDs are integration-derived (e.g. "discord:dm:42", "slack:dm:U123",
# "slack:thread:C1:1700000000.001", "telegram:5556677", "email:thread@host"). They
# come from third-party webhooks, so reflecting an unvalidated value into the
# response body would let an attacker shape stored XSS via a malformed inbound.
# 256 chars is generous (longest observed in practice is ~80).
_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9_:@\-\.\+/=~]{1,256}$")

router = APIRouter()
logger = logging.getLogger(__name__)


class AuditEventOut(BaseModel):
    id: int
    ts: str
    event_type: str
    session_id: str | None
    turn_id: str | None
    actor: str | None
    summary: str
    details: dict[str, Any]


class AuditEventDetailOut(AuditEventOut):
    # Un-truncated drill-down payload (full message bodies, tool inputs/results,
    # specialist queries). Null when nothing extra was captured for this row,
    # or when the row predates the column.
    full: dict[str, Any] | None = None


class AuditListResponse(BaseModel):
    items: list[AuditEventOut]
    total: int
    limit: int
    offset: int
    event_types: list[str]


class AuditGraphNode(BaseModel):
    """One node in the session flow-chart.

    `kind` is the abstract role on the timeline (inbound / executive_turn /
    specialist / tool / knowledge / cache / memory / response / committee)
    derived from `event_type` + context, not a 1:1 mapping. Frontend renders
    icon + color from `kind` first, falls back to `event_type`.
    """
    id: str
    event_id: int
    event_type: str
    kind: str
    label: str
    actor: str | None
    turn_id: str | None
    ts: str


class AuditGraphEdge(BaseModel):
    """Directed edge from one timeline node to another."""
    source: str
    target: str
    # "order" = pure temporal sequencing inside one turn
    # "cause" = causal relation (e.g. executive_turn → specialist via tool_use)
    relation: str = "order"


class AuditGraph(BaseModel):
    nodes: list[AuditGraphNode]
    edges: list[AuditGraphEdge]


class TokenCounts(BaseModel):
    """The token counters every cost view shares: model-call count plus the
    four Anthropic token classes.

    `input_tokens` is fresh (non-cached) prompt input; `cache_read_input_tokens`
    is prompt input served from the cache (~10x cheaper) — together they make
    the cache-hit ratio legible. `calls` is the number of model invocations
    (Executive iterations + specialist consults + committee passes)."""
    calls: int
    input_tokens: int
    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):
    """Token usage for one user-assistant turn, summed across its LLM calls."""
    turn_id: str | None


class CostSummary(TokenCounts):
    """Session-level token totals plus a per-turn breakdown, derived from the
    session's `cache_event` rows. Null when no cache_event was logged."""
    per_turn: list[TurnCost]


class UsageTotals(TokenCounts):
    """Token + cost totals over a window, summed across all `cache_event` rows.

    `cost_usd` is the actual OpenRouter-charged amount captured per call; rows
    that predate cost capture (or non-OpenRouter calls) contribute 0, so the
    figure accrues from go-live rather than being a back-estimated guess."""
    cost_usd: float


class UsageByDay(UsageTotals):
    day: str  # YYYY-MM-DD (UTC, from the `ts` prefix)


class UsageByModel(UsageTotals):
    model: str


class UsageBySource(UsageTotals):
    """One row per call source (the audit `actor`): `executive` chat turns,
    `specialist` chat-turn consults, `specialist_workflow` steps,
    `specialist_research`, `research_synthesis`, `research_watchlist`,
    `triage`, `memory_extractor`, `agent_test`, … — so a heavy day can be
    traced to the part of the system that produced it."""
    source: str


class ScriptUsage(BaseModel):
    """What the sandboxed scripts (run_script) did over the window: how many
    ran (and how many worked), the tool calls they made, the time they took,
    and an upper bound on the model turns those calls would otherwise have
    needed (each call past a script's first, unless batched)."""
    scripts: int = 0
    ok: int = 0
    calls: int = 0
    turns_avoided: int = 0
    duration_ms: int = 0
    in_workflows: int = 0


class PythonJobUsage(BaseModel):
    """What the Python jobs (run_python_job) did over the window: how many ran
    (and worked), how many ran a kept Custom tool or took a chat attachment,
    their time, CPU and largest peak memory, the bytes in and out, and the
    model usage of the turns that ran one (the whole turn, not just the job)."""
    jobs: int = 0
    ok: int = 0
    saved_runs: int = 0
    attachments: int = 0
    duration_ms: int = 0
    cpu_ms: int = 0
    peak_mb_max: int = 0
    bytes_in: int = 0
    bytes_out: int = 0
    turns: int = 0
    input_tokens: int = 0
    output_tokens: int = 0
    cache_read_input_tokens: int = 0
    cost_usd: float = 0.0


class UsageSummary(BaseModel):
    """Aggregate token usage + cost across ALL sessions over an optional time
    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] = []
    scripts: ScriptUsage = ScriptUsage()
    python_jobs: PythonJobUsage = PythonJobUsage()


class Degradation(BaseModel):
    """A dependency failure during the session, surfaced from audit rows so a
    silently-degraded turn is visible to the operator. Today this covers memory
    (Honcho) timeouts/errors — the failure reliably logged with a distinct
    `outcome`. Specialist / RAG failures currently crash or swallow to empty
    without a distinct audit outcome; surfacing those needs their failure paths
    to log one first (follow-up)."""
    kind: str
    reason: str
    count: int
    turn_ids: list[str]
    detail: str | None = None


class AuditSessionResponse(BaseModel):
    session_id: str
    events: list[AuditEventOut]
    graph: AuditGraph
    # Channel inferred from the first integration_inbound event in this
    # session, or null if no inbound was logged (e.g. web chat session).
    channel: str | None = None
    # Token usage aggregated from this session's `cache_event` rows; null when
    # none were logged. Makes per-turn fan-out cost legible in the flow chart.
    cost_summary: CostSummary | None = None
    # Dependency failures detected from this session's audit rows (e.g. memory
    # timeouts/errors) so silently-degraded turns are visible. Empty when clean.
    degradations: list[Degradation] = []


def _resolve_logger(request: Request) -> AuditLogger:
    audit = getattr(request.app.state, "audit", None)
    if isinstance(audit, AuditLogger):
        return audit
    return get_audit_logger()


def _sees_private_rows(request: Request) -> bool:
    """Whether the caller may read rows private to the principal — the rule
    ``/alerts`` and ``/decisions`` use (``people.caller_is_principal``): the
    principal's signed-in email, or no ``x-caller-email`` (the CLI, direct
    curl, local login) once a principal is on the roster. With no principal
    yet, nobody. Fails closed."""
    from openexecutive.api.routes.people import caller_is_principal

    return caller_is_principal(request)


def _view(request: Request) -> dict[str, Any]:
    """Which rows the caller reads, as ``AuditLogger.query`` / ``count``
    filters. The principal: every row, a team member's own shown redacted
    (``_redact``: what was done, not what was said). Anyone else,
    once a principal is on the roster: their own rows alone (none for a
    caller who resolves to nobody). Before then nobody is the principal, so
    everyone reads the rows not private to one, as before. Fails closed."""
    if _sees_private_rows(request):
        # Every row, a teammate's own included: those are shown as actions,
        # their words left out (`_redact`).
        return {"include_private": True, "all_owners": True}
    try:
        from openexecutive.api.routes.chat import _resolve_caller_person_id
        from openexecutive.people.store import find_principal_person

        if find_principal_person() is None:
            return {"include_private": False}
        caller = _resolve_caller_person_id(request)
    except Exception:
        logger.exception("audit: couldn't tell who is reading — showing nothing")
        caller = None
    # Their own rows are all private (to them), so only the owner filter applies.
    return {"include_private": True, "owned_by": caller, "only_owned": True}


def _may_read(event: Any, view: dict[str, Any]) -> bool:
    """Whether a row read by id is one ``view`` lets the caller read."""
    if view.get("only_owned"):
        owner = view.get("owned_by")
        return owner is not None and event.private_to_person == owner
    if event.private_to_person is not None:
        return bool(view.get("all_owners"))
    return not event.private or bool(view.get("include_private"))


def _searchable(view: dict[str, Any]) -> dict[str, Any]:
    """``view`` for a text search: a redacted row's own words must not decide
    whether it matches, so a search leaves other people's rows out."""
    return {k: v for k, v in view.items() if k != "all_owners"}


# What a redacted row keeps of its details: what was done and what it cost,
# never what was said (message text, queries, recipients, results).
_SAFE_DETAIL_KEYS = frozenset({
    "tool", "kind", "ok", "refused", "iteration", "specialist", "department",
    "model", "input_tokens", "output_tokens", "cache_read_input_tokens",
    "cache_creation_input_tokens", "cost_usd", "duration_ms", "direction",
    "channel", "status", "outcome", "is_error", "calls",
})
# A tool label is model-chosen on `call_tool`, so only a plain name is kept.
_TOOL_NAME_RE = re.compile(r"^[A-Za-z0-9_.:\-]{1,80}$")


def _owner_names() -> dict[int, str]:
    try:
        from openexecutive.people.store import list_people

        return {
            int(p.id): (p.full_name or "a teammate")
            for p in list_people(include_archived=True)
            if p.id is not None
        }
    except Exception:
        logger.exception("audit: couldn't read the roster for redacted rows")
        return {}


def _redact(event: Any, names: dict[int, str]) -> Any:
    """A team member's own row as someone else reads it: the action, when and
    in which conversation, with their words left out. The summary is rebuilt
    from the event type and a plain tool name; the details keep only
    ``_SAFE_DETAIL_KEYS``; ``full`` is dropped."""
    import dataclasses

    details = {
        k: v for k, v in (event.details or {}).items()
        if k in _SAFE_DETAIL_KEYS and isinstance(v, (int, float, bool, str))
    }
    tool = details.get("tool")
    if not (isinstance(tool, str) and _TOOL_NAME_RE.match(tool)):
        details.pop("tool", None)
        tool = None
    for key in ("kind", "refused", "status", "outcome", "channel", "direction", "model",
                "specialist", "department"):
        value = details.get(key)
        if isinstance(value, str) and not _TOOL_NAME_RE.match(value):
            details.pop(key)
    if tool:
        kind = details.get("kind")
        action = f"{kind}:{tool}" if isinstance(kind, str) and kind and not tool.startswith(f"{kind}:") else tool
    elif event.event_type == "chat_turn":
        action = "Message" if event.actor == "user" else "Reply"
    else:
        action = event.event_type
    if details.get("refused"):
        action += " refused"
    who = names.get(int(event.private_to_person), "a teammate")
    summary = f"{action} ({who}'s conversation, details private)"
    replace: dict[str, Any] = {"summary": summary, "details": details}
    if hasattr(event, "full"):
        replace["full"] = None
    return dataclasses.replace(event, **replace)


def _shown(events: list[Any], view: dict[str, Any]) -> list[Any]:
    """``events`` as the caller reads them: someone else's own rows redacted."""
    if not view.get("all_owners") or not any(e.private_to_person is not None for e in events):
        return events
    names = _owner_names()
    return [_redact(e, names) if e.private_to_person is not None else e for e in events]


class AuditLogRequest(BaseModel):
    event_type: str
    summary: str
    session_id: str | None = None
    turn_id: str | None = None
    actor: str | None = None
    details: dict[str, Any] | None = None


@router.post("/audit/log", status_code=201)
def create_audit_log(body: AuditLogRequest, request: Request) -> dict[str, int | None]:
    if body.event_type not in EVENT_TYPES:
        raise HTTPException(status_code=422, detail=f"Unknown event_type: {body.event_type!r}")
    audit = _resolve_logger(request)
    row_id = audit.log(
        body.event_type,
        body.summary,
        session_id=body.session_id,
        turn_id=body.turn_id,
        actor=body.actor,
        details=body.details,
    )
    return {"id": row_id}


@router.get("/audit/logs/{event_id}", response_model=AuditEventDetailOut)
def get_audit_log(event_id: int, request: Request) -> AuditEventDetailOut:
    audit = _resolve_logger(request)
    event = audit.get(event_id)
    view = _view(request)
    # A row the caller may not read answers exactly like a missing one.
    if event is None or not _may_read(event, view):
        raise HTTPException(status_code=404, detail="audit event not found")
    [event] = _shown([event], view)
    return AuditEventDetailOut(
        id=event.id,
        ts=event.ts,
        event_type=event.event_type,
        session_id=event.session_id,
        turn_id=event.turn_id,
        actor=event.actor,
        summary=event.summary,
        details=event.details,
        full=event.full,
    )


_KIND_BY_EVENT_TYPE: dict[str, str] = {
    "integration_inbound": "inbound",
    "chat_turn": "response",
    "specialist_consult": "specialist",
    "tool_invocation": "tool",
    "knowledge_retrieval": "knowledge",
    "cache_event": "cache",
    "memory_snapshot": "memory",
    "committee_review": "committee",
    "scheduled_action": "scheduled",
    "alert": "alert",
}


def _node_label(event_type: str, summary: str, details: dict[str, Any]) -> str:
    """Short, glanceable label for a flow-chart node.

    Pulls the most informative field per event_type — full payload is in the
    drill-down drawer, so the label is for orientation only (≤60 chars).
    """
    if event_type == "specialist_consult":
        actor = details.get("specialist") or ""
        return f"{actor}".strip(": ")[:60] or summary[:60]
    if event_type == "tool_invocation":
        tool = details.get("tool")
        if tool:
            return f"{tool}"[:60]
        return summary[:60]
    if event_type == "knowledge_retrieval":
        n = (details.get("builtin_count", 0) or 0) + (details.get("company_count", 0) or 0)
        domain = details.get("domain_filter") or "*"
        if isinstance(domain, list):
            domain = ",".join(domain) or "*"
        return f"RAG[{domain}] · {n} chunks"[:60]
    if event_type == "cache_event":
        cr = details.get("cache_read_input_tokens", 0)
        cc = details.get("cache_creation_input_tokens", 0)
        out = details.get("output_tokens", 0)
        return f"cache r={cr} w={cc} out={out}"[:60]
    if event_type == "memory_snapshot":
        ep = details.get("episodic_chars", 0)
        rag = details.get("retrieved_chars", 0)
        return f"memory · ep={ep}c rag={rag}c"[:60]
    if event_type == "integration_inbound":
        return summary.split(": ", 1)[-1][:60] if ": " in summary else summary[:60]
    if event_type == "committee_review":
        return "committee revision"
    return summary[:60]


def _build_session_graph(events: list[Any]) -> tuple[AuditGraph, str | None]:
    """Derive nodes + edges for a single session timeline.

    Events arrive sorted by id DESC (newest first); for graph construction we
    flip to ascending so causality reads left→right. Channel is inferred from
    the integration_inbound row if present.
    """
    # Ascending order: oldest first → causal flow reads top-to-bottom.
    ordered = sorted(events, key=lambda e: e.id)

    nodes: list[AuditGraphNode] = []
    edges: list[AuditGraphEdge] = []
    channel: str | None = None

    # For each turn_id, keep the "current executive_turn anchor" (the
    # memory_snapshot node, or the first chat_turn if memory_snapshot is
    # missing — both nominally represent the same logical turn entry).
    turn_anchor: dict[str, str] = {}
    # For each turn_id, latest specialist node — tools fired by that
    # specialist link back to it (best-effort; we don't have parent linkage
    # on the wire yet, so order-within-turn is the heuristic).
    last_specialist_in_turn: dict[str, str] = {}
    # The inbound node, if any — first chat_turn after it links from inbound.
    inbound_node_id: str | None = None
    inbound_consumed = False

    for evt in ordered:
        kind = _KIND_BY_EVENT_TYPE.get(evt.event_type, evt.event_type)
        node_id = f"n{evt.id}"
        details = evt.details or {}
        label = _node_label(evt.event_type, evt.summary or "", details)
        nodes.append(
            AuditGraphNode(
                id=node_id,
                event_id=evt.id,
                event_type=evt.event_type,
                kind=kind,
                label=label,
                actor=evt.actor,
                turn_id=evt.turn_id,
                ts=evt.ts,
            )
        )

        # Track channel from inbound details.
        if evt.event_type == "integration_inbound":
            if isinstance(details, dict):
                ch = details.get("channel")
                if isinstance(ch, str) and ch:
                    channel = ch
            inbound_node_id = node_id
            # Reset the consumed flag so each new inbound in a long-running
            # session (e.g., a multi-turn Discord thread) links to its own
            # downstream memory_snapshot / chat_turn instead of becoming
            # orphaned in the graph.
            inbound_consumed = False

        # Edge construction.
        tid = evt.turn_id

        if evt.event_type == "memory_snapshot" and tid:
            # Memory snapshot is the canonical "turn started" anchor.
            turn_anchor[tid] = node_id
            if inbound_node_id is not None and not inbound_consumed:
                edges.append(
                    AuditGraphEdge(
                        source=inbound_node_id, target=node_id, relation="cause"
                    )
                )
                inbound_consumed = True

        elif evt.event_type in {
            "knowledge_retrieval",
            "specialist_consult",
            "tool_invocation",
            "cache_event",
            "committee_review",
        } and tid:
            anchor = turn_anchor.get(tid)
            if anchor is not None:
                edges.append(AuditGraphEdge(source=anchor, target=node_id, relation="order"))
            # A tool right after a specialist on the same turn likely fired
            # because of that specialist's recommendation — link it.
            if evt.event_type == "tool_invocation":
                prev_spec = last_specialist_in_turn.get(tid)
                if prev_spec is not None:
                    edges.append(
                        AuditGraphEdge(source=prev_spec, target=node_id, relation="cause")
                    )
            if evt.event_type == "specialist_consult":
                last_specialist_in_turn[tid] = node_id

        elif evt.event_type == "chat_turn":
            # chat_turn is the *response* row. If we have a turn anchor for
            # the same turn_id, link from there; otherwise treat it as the
            # implicit turn anchor (older sessions without memory_snapshot).
            if tid and tid in turn_anchor:
                edges.append(
                    AuditGraphEdge(
                        source=turn_anchor[tid], target=node_id, relation="cause"
                    )
                )
            elif inbound_node_id is not None and not inbound_consumed:
                edges.append(
                    AuditGraphEdge(
                        source=inbound_node_id, target=node_id, relation="cause"
                    )
                )
                inbound_consumed = True
            if tid:
                turn_anchor.setdefault(tid, node_id)

    return AuditGraph(nodes=nodes, edges=edges), channel


def _compute_cost_summary(events: list[Any]) -> CostSummary | None:
    """Aggregate token usage from a session's `cache_event` rows.

    One cache_event is emitted per model response (Executive iteration,
    specialist consult, committee pass), carrying the token breakdown in
    `details`. We sum per turn_id and overall; missing/garbled fields count as
    0 so a single odd row never breaks the summary. Returns None when the
    session has no cache_event rows (nothing to show)."""
    rows = [e for e in events if e.event_type == "cache_event"]
    if not rows:
        return None
    # query() returns id DESC; sort ascending so per_turn reads oldest -> newest
    # (totals are order-independent, but a future per-turn timeline isn't).
    rows = sorted(rows, key=lambda e: e.id)

    token_fields = (
        "input_tokens",
        "cache_read_input_tokens",
        "cache_creation_input_tokens",
        "output_tokens",
        "web_search_requests",
    )

    def _as_int(value: Any) -> int:
        try:
            return int(value or 0)
        except (TypeError, ValueError):
            return 0

    per_turn_acc: dict[str | None, dict[str, int]] = {}
    order: list[str | None] = []
    for e in rows:
        if e.turn_id not in per_turn_acc:
            per_turn_acc[e.turn_id] = {key: 0 for key in ("calls", *token_fields)}
            order.append(e.turn_id)
        acc = per_turn_acc[e.turn_id]
        acc["calls"] += 1
        details = e.details or {}
        for field in token_fields:
            acc[field] += _as_int(details.get(field))

    per_turn = [TurnCost(turn_id=tid, **per_turn_acc[tid]) for tid in order]
    totals = {
        key: sum(acc[key] for acc in per_turn_acc.values())
        for key in ("calls", *token_fields)
    }
    return CostSummary(per_turn=per_turn, **totals)


def _compute_degradations(events: list[Any]) -> list[Degradation]:
    """Surface dependency failures from the session's audit rows. Today: memory
    (Honcho) timeouts/errors from `peer_memory` rows — the one failure reliably
    logged with a distinct outcome. Normal outcomes (ok / disabled / no_person /
    empty / ...) are NOT degradations. Returns [] when the session ran clean."""
    degraded_outcomes = {"timeout", "error"}
    acc: dict[tuple[str, str], dict[str, Any]] = {}
    order: list[tuple[str, str]] = []
    for e in events:
        if e.event_type != "peer_memory":
            continue
        details = e.details or {}
        outcome = details.get("outcome")
        if outcome not in degraded_outcomes:
            continue
        key = ("memory", str(outcome))
        if key not in acc:
            acc[key] = {"count": 0, "turn_ids": [], "detail": None}
            order.append(key)
        entry = acc[key]
        entry["count"] += 1
        if e.turn_id and e.turn_id not in entry["turn_ids"]:
            entry["turn_ids"].append(e.turn_id)
        if entry["detail"] is None and details.get("error_type"):
            entry["detail"] = str(details["error_type"])
    return [
        Degradation(
            kind=key[0],
            reason=key[1],
            count=acc[key]["count"],
            turn_ids=acc[key]["turn_ids"],
            detail=acc[key]["detail"],
        )
        for key in order
    ]


@router.get(
    "/audit/sessions/{session_id:session}",
    response_model=AuditSessionResponse,
)
def get_audit_session(session_id: str, request: Request) -> AuditSessionResponse:
    """Full timeline + derived graph for one session.

    `session_id` is matched exactly against the indexed column. Returns 404
    only when no events match — empty sessions don't exist in this table.
    Capped at 1000 events per session (the upper limit `query()` enforces);
    a runaway agent session would clip the tail rather than OOM the API.
    """
    if not _SESSION_ID_RE.match(session_id):
        raise HTTPException(status_code=400, detail="invalid session_id format")
    audit = _resolve_logger(request)
    view = _view(request)
    events = _shown(audit.query(session_id=session_id, limit=1000, **view), view)
    if not events:
        raise HTTPException(status_code=404, detail="no events for session_id")
    graph, channel = _build_session_graph(events)
    return AuditSessionResponse(
        session_id=session_id,
        events=[
            AuditEventOut(
                id=e.id,
                ts=e.ts,
                event_type=e.event_type,
                session_id=e.session_id,
                turn_id=e.turn_id,
                actor=e.actor,
                summary=e.summary,
                details=e.details,
            )
            for e in events
        ],
        graph=graph,
        channel=channel,
        cost_summary=_compute_cost_summary(events),
        degradations=_compute_degradations(events),
    )


@router.get("/audit/logs", response_model=AuditListResponse)
def list_audit_logs(
    request: Request,
    event_type: str | None = Query(default=None),
    session_id: str | None = Query(default=None),
    actor: str | None = Query(default=None),
    q: str | None = Query(default=None, description="LIKE search over summary"),
    since: str | None = Query(default=None, description="ISO8601 inclusive lower bound"),
    until: str | None = Query(default=None, description="ISO8601 inclusive upper bound"),
    limit: int = Query(default=100, ge=1, le=1000),
    offset: int = Query(default=0, ge=0),
) -> AuditListResponse:
    audit = _resolve_logger(request)
    view = _view(request)
    if q:
        view = _searchable(view)
    events = audit.query(
        event_type=event_type,
        session_id=session_id,
        actor=actor,
        q=q,
        since=since,
        until=until,
        limit=limit,
        offset=offset,
        **view,
    )
    total = audit.count(
        event_type=event_type,
        session_id=session_id,
        actor=actor,
        q=q,
        since=since,
        until=until,
        **view,
    )
    events = _shown(events, view)
    return AuditListResponse(
        items=[
            AuditEventOut(
                id=e.id,
                ts=e.ts,
                event_type=e.event_type,
                session_id=e.session_id,
                turn_id=e.turn_id,
                actor=e.actor,
                summary=e.summary,
                details=e.details,
            )
            for e in events
        ],
        total=total,
        limit=limit,
        offset=offset,
        event_types=list(EVENT_TYPES),
    )


@router.get("/audit/usage", response_model=UsageSummary)
def get_audit_usage(
    request: Request,
    since: str | None = Query(default=None, description="ISO8601 inclusive lower bound"),
    until: str | None = Query(default=None, description="ISO8601 inclusive upper bound"),
) -> UsageSummary:
    """Aggregate token usage + cost across all sessions, optionally time-bounded.

    Totals plus per-day and per-model breakdowns, summed from `cache_event`
    rows. Unlike `/audit/sessions/{id}` (one session), this spans the whole log
    so an operator can see overall token spend and where it goes.
    """
    audit = _resolve_logger(request)
    data = audit.usage_summary(
        since=since, until=until, include_private=_sees_private_rows(request)
    )
    return UsageSummary(
        since=since,
        until=until,
        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", [])],
        scripts=ScriptUsage(**data.get("scripts", {})),
        python_jobs=PythonJobUsage(**data.get("python_jobs", {})),
    )