pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/gateway/api/sso_login.py

@@ -0,0 +1,168 @@
+"""Sign-in with an org's identity provider: the redirect out, the callback in, a domain's orgs."""
+
+from typing import Annotated
+
+import httpx
+from fastapi import APIRouter, Query, Request
+from fastapi.responses import RedirectResponse
+
+from pinecall.domain.errors import (
+    DeclarationRefused,
+    NotAllowed,
+    NotAvailable,
+    NotFound,
+    PinecallError,
+)
+from pinecall.domain.person import Member
+from pinecall.gateway._deps import GatewayDep, check_knock, client_of, public_url
+from pinecall.gateway._gateway import Gateway
+from pinecall.tenancy import orgs, signin, sso, sso_domains
+from pinecall.tenancy.signin import A_DOMAIN, Handshake
+from pinecall.wire.rest.accounts import DiscoverSsoRequest, DiscoverSsoResponse, SsoOrgRow
+
+router = APIRouter()
+
+
+# The page a sign-in lands on; the URL carries a one-use login code, never a key.
+THE_CONSOLE = "/"
+
+
+# Where a sign-in begun by `pinecall login` lands, to approve the terminal waiting.
+THE_CARD = "/cli"
+
+
+NO_SSO_HERE = "org {org} signs in with no identity provider"
+
+
+NO_HANDSHAKE = (
+    "no sign-in answers to that: it was finished already, it expired, or it never started"
+)
+
+
+ANOTHER_DOMAIN = "{email} is not in a domain {org} signs in with"
+
+
+# No address is known yet at the redirect, so it is counted by the client's address.
+TOO_MANY_SIGN_INS = "too many sign-ins from here: try again in a minute"
+
+
+THE_PROVIDER_SAID = "the sign-in was refused at the provider: {error}"
+
+
+NO_CODE_BACK = "the provider sent no authorization code back"
+
+
+NO_BOX_WIDE = (
+    "box-wide sign-in is not in this version: sign in with a password or the org's provider"
+)
+
+
+FOUND = 302
+
+
+Pairing = Annotated[str | None, Query(description="the terminal waiting to be signed in")]
+
+
+# The same 404 for an org unknown and one with no provider, so slugs are not enumerated.
+@router.get("/v1/login/sso")
+async def start_sso(
+    org: Annotated[str, Query(description="which org's provider, by id or slug")],
+    request: Request,
+    gateway: GatewayDep,
+    pairing: Pairing = None,
+) -> RedirectResponse:
+    """302 to the org's provider, with a state, a nonce and a PKCE challenge."""
+    connections = gateway.connections
+    owner = await orgs.find(connections.pool, org)
+    wired = (
+        None if owner is None else await sso.sso_of(connections.pool, connections.vault, owner.id)
+    )
+    if owner is None or wired is None:
+        raise NotFound(NO_SSO_HERE.format(org=org))
+    await check_knock(gateway, f"{client_of(request)} sso/{owner.slug}", TOO_MANY_SIGN_INS)
+    provider = await sso.discovered(connections.http, wired.client.issuer)
+    redirect_uri = f"{public_url(request, gateway)}{sso.CALLBACK}"
+    begun = await sso.handshake(
+        gateway.signins.handshakes, redirect_uri, org=owner.id, pairing=pairing
+    )
+    return RedirectResponse(sso.authorization_url(provider, wired.client, begun), FOUND)
+
+
+# A refusal mid-redirect goes back to the sign-in page as `?refused=`: a JSON body there is a
+# dead end. A state nobody began is the one refusal answered as JSON.
+@router.get("/v1/login/sso/callback")
+async def finish_sso(
+    state: str, gateway: GatewayDep, code: str | None = None, error: str | None = None
+) -> RedirectResponse:
+    """The code exchanged, the person seated, and 302 to the console with a login code."""
+    begun = await gateway.signins.handshakes.spend(state)
+    if begun is None:
+        raise DeclarationRefused(NO_HANDSHAKE)
+    if error is not None:
+        return _refused(THE_PROVIDER_SAID.format(error=error))
+    if not code:
+        return _refused(NO_CODE_BACK)
+    try:
+        member = await _seated(gateway, begun, code)
+    except PinecallError as refusal:
+        return _refused(str(refusal))
+    login, _ = await gateway.signins.codes.mint(member)
+    return RedirectResponse(_landing(begun.pairing, login), FOUND)
+
+
+# Says which orgs a domain signs in with, never whether the address is anybody's.
+@router.post("/v1/login/sso/discover")
+async def discover_sso(
+    body: DiscoverSsoRequest, request: Request, gateway: GatewayDep
+) -> DiscoverSsoResponse:
+    """The orgs whose provider signs in this address's domain, oldest first."""
+    connections = gateway.connections
+    email = body.email.strip().lower()
+    await check_knock(
+        gateway, f"{client_of(request)} sso/{email}", signin.TOO_MANY.format(email=email)
+    )
+    domain = email.rpartition("@")[2]
+    if not A_DOMAIN.match(domain):
+        return DiscoverSsoResponse(orgs=[])
+    rows: list[SsoOrgRow] = []
+    for wired in await sso.sso_with_domain(connections.pool, connections.vault, domain):
+        org = await orgs.find(connections.pool, wired.org)
+        if org is not None:
+            rows.append(SsoOrgRow(org=org.id, slug=org.slug, name=org.name))
+    return DiscoverSsoResponse(orgs=rows)
+
+
+@router.get("/v1/login/google")
+async def google_sign_in() -> RedirectResponse:
+    """Box-wide "Continue with Google", which this version does not have."""
+    raise NotAvailable(NO_BOX_WIDE)
+
+
+@router.get("/v1/login/google/callback")
+async def google_callback() -> RedirectResponse:
+    """Box-wide Google's callback, which this version does not have."""
+    raise NotAvailable(NO_BOX_WIDE)
+
+
+async def _seated(gateway: Gateway, begun: Handshake, code: str) -> Member:
+    connections = gateway.connections
+    named = begun.org or ""
+    wired = await sso.sso_of(connections.pool, connections.vault, named)
+    org = await orgs.find(connections.pool, named)
+    if wired is None or org is None:
+        raise NotFound(NO_SSO_HERE.format(org=named))
+    claims = await sso.vouched_for(connections.http, wired.client, begun, code)
+    proven = await sso_domains.verified_domains(connections.pool, org.id)
+    if not wired.admits(claims.email) or claims.email.rpartition("@")[2].lower() not in proven:
+        raise NotAllowed(ANOTHER_DOMAIN.format(email=claims.email, org=org.slug))
+    return await sso.seat_vouched(connections.pool, org, wired, claims)
+
+
+def _landing(pairing: str | None, code: str) -> str:
+    if pairing is None:
+        return f"{THE_CONSOLE}?{httpx.QueryParams({'login': code})}"
+    return f"{THE_CARD}?{httpx.QueryParams({'c': pairing, 'login': code})}"
+
+
+def _refused(sentence: str) -> RedirectResponse:
+    return RedirectResponse(f"{THE_CONSOLE}?{httpx.QueryParams({'refused': sentence})}", FOUND)

pinecall/gateway/api/threads.py

@@ -0,0 +1,187 @@
+"""An agent's WhatsApp inbox by contact: the threads, one thread, read, written to."""
+
+import time
+from typing import Annotated
+
+from fastapi import APIRouter, Query
+from pydantic import BaseModel, Field
+
+from pinecall.channels.whatsapp import WINDOW_S
+from pinecall.domain.errors import (
+    Conflict,
+    NotFound,
+)
+from pinecall.domain.names import THE_WIDGET, parse_channel
+from pinecall.domain.scope import Scope
+from pinecall.gateway import _deps
+from pinecall.gateway._deps import Acting, CallsKey, GatewayDep, ScopeDep, TalkKey
+from pinecall.gateway._gateway import Gateway
+from pinecall.log import facts, inbox, queries
+from pinecall.tenancy import keys
+from pinecall.wire.commands import SayVerb, SupervisorVerb
+from pinecall.wire.frames import Entry
+from pinecall.wire.parts import Supervisor, ThreadKind
+from pinecall.wire.rest.calls import (
+    ThreadLast,
+    ThreadList,
+    ThreadMessage,
+    ThreadMessageRequest,
+    ThreadMessageResponse,
+    ThreadResponse,
+    ThreadRow,
+)
+
+router = APIRouter()
+
+
+THREADS_A_PAGE = 30
+
+# The calls merged into one thread, newest first: each costs a log read.
+CALLS_IN_A_THREAD = 20
+
+NO_THREAD = "no thread with {contact} on agent {agent} in this corner"
+
+ONLY_WHATSAPP = (
+    "a message is written on a WhatsApp thread, and {contact}'s newest call is {channel}"
+)
+
+WINDOW_CLOSED = (
+    "WhatsApp's window with {contact} closed 24 h after their last message: only a template "
+    "reaches them now"
+)
+
+NOTHING_OPEN = (
+    "{contact}'s conversation went quiet and is sealed: their next message opens a new one"
+)
+
+
+class ThreadQuery(BaseModel):
+    """One page of an inbox: after the cursor of the last one, so many contacts."""
+
+    after: str | None = None
+    limit: int = Field(THREADS_A_PAGE, ge=1, le=_deps.LONGEST_LIST)
+
+
+@router.get("/v1/agents/{slug}/threads")
+async def list_threads(
+    slug: str,
+    key: CallsKey,
+    where: ScopeDep,
+    gateway: GatewayDep,
+    page: Annotated[ThreadQuery, Query()],
+) -> ThreadList:
+    """The agent's contacts, the one that moved last first, with what this reader has not read."""
+    wanted = inbox.Inbox(where, slug, _reader_of(key))
+    found = await inbox.threads(
+        gateway.connections.pool, wanted, after=page.after, limit=page.limit
+    )
+    return ThreadList(threads=[_line_of(row) for row in found.rows], next=found.next)
+
+
+@router.get("/v1/agents/{slug}/threads/{contact}")
+async def get_thread(
+    slug: str, contact: str, _key: CallsKey, where: ScopeDep, gateway: GatewayDep
+) -> ThreadResponse:
+    """A contact's calls with the agent merged into one thread, oldest first."""
+    calls = await _thread_of(gateway, where, slug, contact)
+    facts = await queries.facts_of_calls(gateway.connections.pool, calls)
+    messages: list[ThreadMessage] = []
+    for call in reversed(calls):
+        if call in facts:
+            messages += _said_on(facts[call], await gateway.logs.store.whole(call))
+    name = next((facts[call].name for call in calls if call in facts and facts[call].name), None)
+    return ThreadResponse(contact=contact, name=name, messages=messages)
+
+
+# The read cursor is the person's; a server's key keeps its own.
+@router.post("/v1/agents/{slug}/threads/{contact}/read", status_code=204)
+async def mark_thread_read(
+    slug: str, contact: str, key: CallsKey, where: ScopeDep, gateway: GatewayDep
+) -> None:
+    """This reader has read the thread up to now."""
+    await _thread_of(gateway, where, slug, contact)
+    await inbox.read(
+        gateway.connections.pool, inbox.Inbox(where, slug, _reader_of(key)), contact, time.time()
+    )
+
+
+# A supervisor's `say` on the open conversation, sent to the contact by its reply tap. Meta lets
+# a business write freely only within 24 h of the contact's last message.
+@router.post("/v1/agents/{slug}/threads/{contact}/messages", status_code=202)
+async def send_thread_message(
+    slug: str, contact: str, body: ThreadMessageRequest, key: TalkKey, gateway: GatewayDep
+) -> ThreadMessageResponse:
+    """Say something as the agent on the contact's open WhatsApp conversation."""
+    where = keys.scope_of(key.bearer, key.env)
+    newest = (await _thread_of(gateway, where, slug, contact))[0]
+    facts = (await queries.facts_of_calls(gateway.connections.pool, [newest])).get(newest)
+    channel = None if facts is None else facts.channel
+    if facts is None or channel != "whatsapp":
+        raise Conflict(ONLY_WHATSAPP.format(contact=contact, channel=channel))
+    # The log's own clock, which stamped when the contact last wrote.
+    if gateway.logs.store.clock() - max(facts.heard_at, default=0.0) > WINDOW_S:
+        raise Conflict(WINDOW_CLOSED.format(contact=contact))
+    served = gateway.live.calls.get(newest)
+    if served is None or served.session is None:
+        raise Conflict(NOTHING_OPEN.format(contact=contact))
+    member = key.bearer.member
+    by = Supervisor(id=_reader_of(key), name=None if member is None else member.name)
+    await served.session.supervise(SupervisorVerb(by=by, verb=SayVerb(text=body.text)))
+    return ThreadMessageResponse(contact=contact, call=newest)
+
+
+async def _thread_of(gateway: Gateway, where: Scope, slug: str, contact: str) -> list[str]:
+    calls = await inbox.calls_with(
+        gateway.connections.pool, where, slug, contact, limit=CALLS_IN_A_THREAD
+    )
+    if not calls:
+        raise NotFound(NO_THREAD.format(contact=contact, agent=slug))
+    return calls
+
+
+def _reader_of(key: Acting) -> str:
+    return key.bearer.key.subject or key.bearer.key.key_id
+
+
+def _line_of(row: inbox.InboxRow) -> ThreadRow:
+    newest = row.newest
+    kind: ThreadKind = "call" if newest.spoken else ("in" if newest.last_in else "out")
+    data = newest.outcome if newest.spoken else newest.last_text
+    return ThreadRow(
+        contact=row.contact,
+        name=row.name,
+        channel_last=parse_channel(newest.channel or THE_WIDGET),
+        last=ThreadLast(text=data, at=row.moved_at, kind=kind),
+        unread=row.unread,
+        calls=row.calls,
+    )
+
+
+# A written call is its turns; a spoken call is one pill with its length and whether it came up.
+def _said_on(call_facts: facts.CallFacts, entries: list[Entry]) -> list[ThreadMessage]:
+    channel = parse_channel(call_facts.channel or THE_WIDGET)
+    if not call_facts.spoken:
+        return [
+            ThreadMessage(
+                kind="in" if entry.type == "turn.user" else "out",
+                text=str(entry.data.get("text") or ""),
+                at=entry.ts,
+                call=call_facts.call,
+                channel=channel,
+            )
+            for entry in entries
+            if entry.type in {"turn.user", "turn.agent"}
+        ]
+    ended = next((entry for entry in entries if entry.type == "call.ended"), None)
+    lasted = None if ended is None else ended.data.get("duration_s")
+    return [
+        ThreadMessage(
+            kind="call",
+            text=call_facts.outcome,
+            at=entries[0].ts if entries else 0.0,
+            call=call_facts.call,
+            channel=channel,
+            duration_s=float(lasted) if isinstance(lasted, int | float) else None,
+            answered=any(entry.type == "call.started" for entry in entries),
+        )
+    ]

pinecall/gateway/api/usage.py

@@ -0,0 +1,303 @@
+"""The org's meters: the usage feed, a window's insights, an agent's drift, what the org may use."""
+
+import re
+from datetime import UTC, date, datetime, timedelta
+from typing import Annotated
+
+from fastapi import APIRouter, Query
+from pydantic import BaseModel
+
+from pinecall.channels import routes
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.org import Quotas
+from pinecall.gateway._deps import ActingDep, CallsKey, GatewayDep, ScopeDep, UsageKey
+from pinecall.log import drift
+from pinecall.log.drift import Side, Tally
+from pinecall.log.reduce import Usage, UsageRow, totals_by_org
+from pinecall.log.store import DEFAULT_LIMIT
+from pinecall.log.usage import A_DAY_S, AgentWindow, WindowDay, counted_window, metered_page
+from pinecall.tenancy import admission, people, scopes, usage
+from pinecall.tenancy.keys import check_agent
+from pinecall.wire.rest.usage import (
+    Drift,
+    DriftSide,
+    DriftVersion,
+    Insights,
+    InsightsAgent,
+    InsightsBudget,
+    InsightsChannels,
+    InsightsConversations,
+    InsightsDay,
+    InsightsEnding,
+    InsightsSpend,
+    Limit,
+    Limits,
+    UsagePage,
+    UsageTotals,
+)
+from pinecall.wire.rest.usage import UsageRow as UsageRowResponse
+
+router = APIRouter()
+
+
+# An org carries no timezone, so a day is cut in UTC and the answer says so.
+TIMEZONE = "UTC"
+
+
+# The windows the console offers, in whole UTC days: today, a week, a month.
+WINDOW_DAYS = (1, 7, 30)
+
+
+NOT_A_WINDOW = "days={days} is not a window: one of 1, 7 or 30"
+
+
+A_VERSION = re.compile(r"v(\d+)")
+
+
+NOT_A_SIDE = "{text!r} is neither a day (YYYY-MM-DD) nor a version (v3)"
+
+
+BOTH_SIDES = "a drift between versions names both: before=v3&after=v4"
+
+
+class InsightsQuery(BaseModel):
+    """What insights count: the window's last day (today), its days, one agent or every one."""
+
+    day: date | None = None
+    days: int = 1
+    agent: str | None = None
+
+
+class DriftQuery(BaseModel):
+    """What a drift compares: an agent, two days (today and the day before) or two versions."""
+
+    agent: str
+    before: str | None = None
+    after: str | None = None
+
+
+# The cursor is the store's position of the last row read: a billing consumer resumes from it
+# and counts nothing twice.
+@router.get("/v1/usage")
+async def usage_feed(
+    key: UsageKey,
+    gateway: GatewayDep,
+    after: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=DEFAULT_LIMIT)] = DEFAULT_LIMIT,
+) -> UsagePage:
+    """The org's metered rows after the cursor, their totals, and the next cursor."""
+    page = await metered_page(gateway.logs.store, after=after, limit=limit, org=key.org)
+    totals = totals_by_org(page.rows).get(key.org)
+    return UsagePage(
+        rows=[usage_row_response(row) for row in page.rows],
+        totals=None if totals is None else usage_totals(totals),
+        next=page.next,
+    )
+
+
+# The window is the scope's, or one agent's of it; the budget is the org's across both worlds and
+# its month is the window's last day's, since it is one bill.
+@router.get("/v1/insights")
+async def insights(
+    key: CallsKey,
+    scope: ScopeDep,
+    gateway: GatewayDep,
+    query: Annotated[InsightsQuery, Query()],
+) -> Insights:
+    """Whole UTC days of the key's world and scope at a glance, and the month's spend."""
+    if query.days not in WINDOW_DAYS:
+        raise DeclarationRefused(NOT_A_WINDOW.format(days=query.days))
+    if query.agent is not None:
+        check_agent(key.bearer, query.agent)
+    pool = gateway.connections.pool
+    last = query.day or datetime.now(UTC).date()
+    first = last - timedelta(days=query.days - 1)
+    start, end = _opening(first), _opening(last) + A_DAY_S
+    counted = await counted_window(pool, scope, start, end, query.agent)
+    spent = await usage.spent_in(pool, key.org, last)
+    quotas = await admission.quotas_of(pool, key.org, key.env)
+    return Insights(
+        day=last.isoformat(),
+        days=query.days,
+        timezone=TIMEZONE,
+        conversations=InsightsConversations(now=counted.calls, before=counted.before),
+        resolved_rate=counted.unescalated / counted.finished if counted.finished else None,
+        median_e2e_s=counted.median_e2e,
+        spend_usd=counted.spent,
+        channels=_channels(counted.channels),
+        judged=counted.judged,
+        passed=counted.passed,
+        escalated=counted.escalated,
+        mean_length_s=counted.mean_length,
+        endings=[InsightsEnding(reason=reason, count=count) for reason, count in counted.endings],
+        series=[_day(day) for day in counted.days],
+        sessions_total=counted.total,
+        live=counted.live,
+        agents=[
+            InsightsAgent(
+                slug=agent.slug, calls=agent.calls, score=agent.score, spend=_spend(agent)
+            )
+            for agent in counted.agents
+        ],
+        stages=await drift.stages_of_window(pool, scope, first, last, query.agent),
+        budget=InsightsBudget(limit_usd=quotas.budget_usd, spent_usd_month=spent),
+    )
+
+
+# Folded when each call was sealed (log/drift.py): two days or two versions read a few rows each.
+@router.get("/v1/insights/drift")
+async def insights_drift(
+    key: CallsKey, scope: ScopeDep, gateway: GatewayDep, query: Annotated[DriftQuery, Query()]
+) -> Drift:
+    """What moved between two days or versions of an agent, and the versions run or set."""
+    check_agent(key.bearer, query.agent)
+    pool = gateway.connections.pool
+    before, after = _sides(query)
+    tallies = (
+        await drift.tally(pool, scope, query.agent, before),
+        await drift.tally(pool, scope, query.agent, after),
+    )
+    judges, stages = drift.compared(*tallies)
+    ran = tallies[0].versions | tallies[1].versions
+    days = [side.day for side in (before, after) if side.day is not None]
+    window = (_opening(min(days)), _opening(max(days)) + A_DAY_S) if days else (0.0, 0.0)
+    noted = await scopes.versions_noted(pool, scope, query.agent, ran, window)
+    return Drift(
+        agent=query.agent,
+        world=scope.env,
+        before=_side(before, tallies[0]),
+        after=_side(after, tallies[1]),
+        judges=judges,
+        stages=stages,
+        versions=[
+            DriftVersion(
+                version=row.version,
+                holder=row.holder,
+                author=row.author,
+                note=row.note,
+                set_at=row.set_at.timestamp(),
+                ran_before=row.version in tallies[0].versions,
+                ran_after=row.version in tallies[1].versions,
+            )
+            for row in noted
+        ],
+    )
+
+
+# Any key of the org. `used` reads what admission reads, so this page and a refusal agree.
+@router.get("/v1/limits")
+async def limits(key: ActingDep, gateway: GatewayDep) -> Limits:
+    """Each quota of the key's world as {limit, used}, the lends, and where to buy more."""
+    pool, org, env = gateway.connections.pool, key.org, key.env
+    quotas = await admission.quotas_of(pool, org, env)
+    used = await usage.used(pool, org, env, usage.month_of(gateway.logs.store.clock()))
+    return Limits(
+        minutes=Limit(limit=quotas.minutes, used=used.minutes),
+        messages=Limit(limit=quotas.messages, used=used.messages),
+        llm_tokens=Limit(limit=quotas.llm_tokens, used=used.input_tokens + used.output_tokens),
+        concurrent_calls=Limit(limit=quotas.concurrent_calls, used=gateway.live.running(org, env)),
+        agents=Limit(limit=quotas.agents, used=len(gateway.sockets.slugs(org))),
+        seats=Limit(limit=quotas.seats, used=await people.seated(pool, org)),
+        numbers=Limit(limit=quotas.numbers, used=await routes.managed_in(pool, org, env)),
+        lends=_lends(quotas),
+        billing_url=gateway.connections.settings.billing_url,
+        world=env,
+    )
+
+
+def usage_row_response(row: UsageRow) -> UsageRowResponse:
+    """A folded row as the feed sends it."""
+    return UsageRowResponse(
+        cursor=row.cursor,
+        org=row.org,
+        agent=row.agent,
+        call=row.call,
+        type=row.type,
+        at=row.at,
+        minutes=row.used.minutes,
+        messages=row.used.messages,
+        input_tokens=row.used.input_tokens,
+        output_tokens=row.used.output_tokens,
+        characters=row.used.characters,
+        judge_calls=row.used.judge_calls,
+        cost_usd=row.used.cost_usd,
+    )
+
+
+def usage_totals(used: Usage) -> UsageTotals:
+    """A sum of usage as the feed sends it."""
+    return UsageTotals(
+        calls=used.calls,
+        minutes=used.minutes,
+        messages=used.messages,
+        input_tokens=used.input_tokens,
+        output_tokens=used.output_tokens,
+        characters=used.characters,
+        judge_calls=used.judge_calls,
+        cost_usd=used.cost_usd,
+    )
+
+
+# Two days by default: today and the day before it, in UTC.
+def _sides(query: DriftQuery) -> tuple[Side, Side]:
+    after = _side_of(query.after) if query.after is not None else Side(day=datetime.now(UTC).date())
+    if query.before is not None:
+        return _side_of(query.before), after
+    if after.day is None:
+        raise DeclarationRefused(BOTH_SIDES)
+    return Side(day=after.day - timedelta(days=1)), after
+
+
+def _side_of(text: str) -> Side:
+    version = A_VERSION.fullmatch(text)
+    if version is not None:
+        return Side(version=int(version.group(1)))
+    try:
+        return Side(day=date.fromisoformat(text))
+    except ValueError as refused:
+        raise DeclarationRefused(NOT_A_SIDE.format(text=text)) from refused
+
+
+def _side(side: Side, tallied: Tally) -> DriftSide:
+    return DriftSide(
+        day=None if side.day is None else side.day.isoformat(),
+        version=side.version,
+        versions=sorted(tallied.versions),
+    )
+
+
+def _channels(counted: dict[str, int]) -> InsightsChannels:
+    return InsightsChannels(
+        phone=counted["phone"], web=counted["web"], whatsapp=counted["whatsapp"]
+    )
+
+
+def _day(day: WindowDay) -> InsightsDay:
+    return InsightsDay(
+        day=day.day.isoformat(),
+        **day.channels,
+        spend_usd=day.spent,
+        judged=day.judged,
+        passed=day.passed,
+    )
+
+
+def _spend(agent: AgentWindow) -> InsightsSpend:
+    total = sum(agent.spend.values())
+    return InsightsSpend(
+        llm_usd=agent.spend["llm"],
+        stt_usd=agent.spend["stt"],
+        tts_usd=agent.spend["tts"],
+        phone_usd=agent.spend["phone"],
+        platform_usd=agent.spend["platform"],
+        minutes=round(agent.minutes, 3),
+        per_minute_usd=round(total / agent.minutes, 6) if agent.minutes > 0 else None,
+    )
+
+
+def _lends(quotas: Quotas) -> list[str] | None:
+    return None if quotas.lends is None else sorted(quotas.lends)
+
+
+def _opening(day: date) -> float:
+    return datetime(day.year, day.month, day.day, tzinfo=UTC).timestamp()