Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(metering): count each tenant's messages and turns as they happen (CHOO-2625)

Petr Bauch5d6e5cf4b9a2
diff --git a/core/switch_core/clients/client_factory.py b/core/switch_core/clients/client_factory.py
index 50b75b1e8..a68fb64ee 100644
--- a/core/switch_core/clients/client_factory.py
+++ b/core/switch_core/clients/client_factory.py
@@ -12,6 +12,7 @@ from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.media_store import MediaStore
from switch_core.db.stores.message_store import MessageStore
from switch_core.db.stores.room_store import RoomStore
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.messages.notify import MessageListener
from switch_core.transport import MessageTransport
from switch_core.transport.ephemeral import EphemeralBus
@@ -30,6 +31,7 @@ class ClientFactory:
config: SwitchConfig,
room_store: RoomStore,
message_store: MessageStore,
+ usage_store: UsageStore,
media_store: MediaStore,
listener: MessageListener,
invites: InviteBus,
@@ -40,6 +42,7 @@ class ClientFactory:
self._config = config
self._room_store = room_store
self._message_store = message_store
+ self._usage_store = usage_store
self._media_store = media_store
self._listener = listener
self._invites = invites
@@ -95,6 +98,7 @@ class ClientFactory:
session_factory=self._session_factory,
room_store=self._room_store,
message_store=self._message_store,
+ usage_store=self._usage_store,
media_store=self._media_store,
listener=self._listener,
invites=self._invites,
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index c31d70019..d7b69dd85 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -1,5 +1,6 @@
import uuid
from datetime import datetime
+from enum import StrEnum
from sqlalchemy import (
DDL,
@@ -2305,6 +2306,57 @@ for _table, _triggers in (
event.listen(_table, "after_create", DDL(_ddl).execute_if(dialect="postgresql"))
+# ── Usage metering ───────────────────────────────────────────────────────────
+
+
+class UsageMetric(StrEnum):
+ MESSAGES = "messages"
+ TURNS = "turns"
+ INPUT_TOKENS = "input_tokens"
+ OUTPUT_TOKENS = "output_tokens"
+
+
+class TenantUsage(TenantScoped, Base):
+ """What a tenant has consumed, counted as it happens, one row per hour.
+
+ The record that quotas are enforced against and that billing will read,
+ so it is kept apart from the rows it counts: deleting a room cascades to
+ its messages, and a count derived from `messages` would forget usage the
+ tenant has already spent. Written in the same transaction as the thing it
+ counts, so the two cannot disagree.
+
+ Hourly buckets because a budget period is configurable: any period of a
+ whole number of hours is a sum over these rows, while a coarser bucket
+ would fix the shortest period a budget can have.
+
+ `client_id` is who consumed it: the sender of a message, or the client of
+ the agent a turn ran for. No foreign key, so a count outlives the client it
+ names. `model` is empty where a metric has none.
+ """
+
+ __tablename__ = "tenant_usage"
+ __table_args__ = (
+ # Leads on the metric so "this tenant's turns since a moment" — the
+ # shape every budget check asks — is a range scan on the key itself.
+ PrimaryKeyConstraint(
+ "tenant_id", "metric", "bucket_start", "client_id", "model"
+ ),
+ CheckConstraint(
+ "metric IN ({})".format(", ".join(f"'{m}'" for m in UsageMetric)),
+ name="ck_tenant_usage_metric",
+ ),
+ CheckConstraint("amount > 0", name="ck_tenant_usage_amount"),
+ )
+
+ metric: Mapped[str] = mapped_column(Text, nullable=False)
+ bucket_start: Mapped[datetime] = mapped_column(
+ DateTime(timezone=True), nullable=False
+ )
+ client_id: Mapped[str] = mapped_column(Text, nullable=False)
+ model: Mapped[str] = mapped_column(Text, nullable=False)
+ amount: Mapped[int] = mapped_column(BigInteger, nullable=False)
+
+
# Same reasoning as the notify trigger above: `create_all` has to build the
# row-level-security policies too, or the isolation test would pass against a
# schema that has none. See `db/rls_ddl.py` for the DDL and why it takes this
diff --git a/core/switch_core/db/stores/session_activity_store.py b/core/switch_core/db/stores/session_activity_store.py
index 44cce1404..c271fbc25 100644
--- a/core/switch_core/db/stores/session_activity_store.py
+++ b/core/switch_core/db/stores/session_activity_store.py
@@ -101,6 +101,27 @@ class ApprovalRequestStore:
class SessionActivityStore:
+ async def status_for_update(
+ self,
+ session: AsyncSession,
+ agent_id: str,
+ session_id: str,
+ turn_id: str,
+ item_id: str,
+ ) -> str | None:
+ """The row's stored status, locked until the transaction ends, or None."""
+ status: str | None = await session.scalar(
+ select(SessionActivityItem.status)
+ .where(
+ SessionActivityItem.agent_id == agent_id,
+ SessionActivityItem.session_id == session_id,
+ SessionActivityItem.turn_id == turn_id,
+ SessionActivityItem.item_id == item_id,
+ )
+ .with_for_update()
+ )
+ return status
+
async def upsert(self, session: AsyncSession, item: SessionActivityItem) -> bool:
"""Record `item` unless a revision at least as new is stored.
diff --git a/core/switch_core/db/stores/usage_store.py b/core/switch_core/db/stores/usage_store.py
new file mode 100644
index 000000000..0ea4b13f6
--- /dev/null
+++ b/core/switch_core/db/stores/usage_store.py
@@ -0,0 +1,124 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+from sqlalchemy import and_, func, literal, select
+from sqlalchemy.dialects.postgresql import insert
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from switch_core.db.models import Client, TenantUsage, UsageMetric
+
+
+@dataclass(frozen=True)
+class UsageTotal:
+ """One consumer's total of one metric over a window.
+
+ `client_name` and `client_type` are null for a client that no longer
+ exists; the usage it spent is still the tenant's.
+ """
+
+ metric: str
+ client_id: str
+ client_name: str | None
+ client_type: str | None
+ model: str
+ amount: int
+
+
+class UsageStore:
+ async def record(
+ self,
+ session: AsyncSession,
+ *,
+ tenant_id: str,
+ metric: UsageMetric,
+ client_id: str,
+ model: str,
+ amount: int,
+ ) -> None:
+ """Add `amount` to the current hour's count, in the caller's transaction.
+
+ The bucket is the database's clock, not this process's, so every writer
+ agrees on which hour it is. Hours are taken in UTC so a deployment's
+ `TimeZone` setting cannot move a bucket boundary.
+ """
+ if amount <= 0:
+ raise ValueError(f"usage amount must be positive, got {amount}")
+ bucket = func.date_trunc("hour", func.now(), literal("UTC"))
+ statement = insert(TenantUsage).values(
+ tenant_id=tenant_id,
+ metric=metric.value,
+ bucket_start=bucket,
+ client_id=client_id,
+ model=model,
+ amount=amount,
+ )
+ statement = statement.on_conflict_do_update(
+ index_elements=[
+ "tenant_id",
+ "metric",
+ "bucket_start",
+ "client_id",
+ "model",
+ ],
+ set_={"amount": TenantUsage.amount + statement.excluded.amount},
+ )
+ await session.execute(statement)
+
+ async def totals(
+ self,
+ session: AsyncSession,
+ *,
+ tenant_id: str,
+ since: datetime,
+ until: datetime,
+ ) -> list[UsageTotal]:
+ """Totals per metric, consumer and model for buckets in `[since, until)`.
+
+ Buckets are whole hours, so `since` is rounded down to the hour it
+ falls in and a bucket counts if it starts before `until`.
+
+ Names the tenant explicitly as well as relying on the bound session:
+ the policy does not apply on an owner connection, and a fan-out that
+ leaned on it alone would count every tenant's rows as this one's.
+ """
+ rows = await session.execute(
+ select(
+ TenantUsage.metric,
+ TenantUsage.client_id,
+ Client.display_name,
+ Client.type,
+ TenantUsage.model,
+ func.sum(TenantUsage.amount),
+ )
+ .outerjoin(
+ Client,
+ and_(
+ Client.id == TenantUsage.client_id,
+ Client.tenant_id == TenantUsage.tenant_id,
+ ),
+ )
+ .where(
+ TenantUsage.tenant_id == tenant_id,
+ TenantUsage.bucket_start >= func.date_trunc("hour", since, "UTC"),
+ TenantUsage.bucket_start < until,
+ )
+ .group_by(
+ TenantUsage.metric,
+ TenantUsage.client_id,
+ Client.display_name,
+ Client.type,
+ TenantUsage.model,
+ )
+ .order_by(TenantUsage.metric, TenantUsage.client_id, TenantUsage.model)
+ )
+ return [
+ UsageTotal(
+ metric=metric,
+ client_id=client_id,
+ client_name=client_name,
+ client_type=client_type,
+ model=model,
+ amount=int(amount),
+ )
+ for metric, client_id, client_name, client_type, model, amount in rows
+ ]
diff --git a/core/switch_core/main.py b/core/switch_core/main.py
index f258cbe27..389a00684 100644
--- a/core/switch_core/main.py
+++ b/core/switch_core/main.py
@@ -120,6 +120,7 @@ from switch_core.db.stores.server_connector_store import ServerConnectorStore
from switch_core.db.stores.task_store import TaskStore
from switch_core.db.stores.template_store import TemplateStore
from switch_core.db.stores.tenant_store import TenantStore
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.db.stores.user_store import UserStore
from switch_core.db.tenant_lookup import all_tenant_ids
from switch_core.gateway.app import create_gateway_app
@@ -388,6 +389,7 @@ async def run(config: SwitchConfig) -> None:
room_group_store = RoomGroupStore()
room_role_store = RoomRoleStore()
message_store = MessageStore()
+ usage_store = UsageStore()
media_store = MediaStore()
template_store = TemplateStore()
@@ -469,6 +471,7 @@ async def run(config: SwitchConfig) -> None:
config=config,
room_store=room_store,
message_store=message_store,
+ usage_store=usage_store,
media_store=media_store,
listener=message_listener,
invites=invites,
diff --git a/core/switch_core/migrations/versions/c7e4a91d3b20_tenant_usage.py b/core/switch_core/migrations/versions/c7e4a91d3b20_tenant_usage.py
new file mode 100644
index 000000000..046663ac9
--- /dev/null
+++ b/core/switch_core/migrations/versions/c7e4a91d3b20_tenant_usage.py
@@ -0,0 +1,75 @@
+"""per-tenant usage, counted as it happens
+
+Revision ID: c7e4a91d3b20
+Revises: c4e9a1f7b203
+
+The metering record quotas are enforced against and billing will read: one row
+per tenant, metric, hour, consumer and model, incremented in the same
+transaction as the message or turn it counts (CHOO-2625).
+
+It is a table of its own rather than a count over ``messages`` because usage
+must outlive what it counts: deleting a room cascades to its messages, and a
+tenant's spend cannot shrink when it tidies up. Nothing here can be backfilled
+— counting starts when this migration runs.
+
+Buckets are an hour wide so that a budget period can be any whole number of
+hours; the key leads on the metric so the question a budget asks, "this
+tenant's turns since a moment", is a range scan on the key itself.
+
+``client_id`` carries no foreign key, so a count outlives the client it names.
+
+The row-level-security DDL is a verbatim copy of ``switch_core/db/rls_ddl.py``
+as it stood when this migration was written, copied rather than imported for
+the reason ``265ed188ad6f`` gives.
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "c7e4a91d3b20"
+down_revision: str | Sequence[str] | None = "c4e9a1f7b203"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+REQUIRE_TENANT_FUNCTION_NAME = "require_tenant_id"
+POLICY_NAME = "tenant_isolation"
+
+_PREDICATE = f'"tenant_id" = (SELECT {REQUIRE_TENANT_FUNCTION_NAME}())'
+_CREATE_POLICY = (
+ f'CREATE POLICY {POLICY_NAME} ON "tenant_usage"\n'
+ f" FOR ALL\n"
+ f" USING ({_PREDICATE})\n"
+ f" WITH CHECK ({_PREDICATE})"
+)
+
+
+def upgrade() -> None:
+ op.create_table(
+ "tenant_usage",
+ sa.Column("tenant_id", sa.Text(), nullable=False),
+ sa.Column("metric", sa.Text(), nullable=False),
+ sa.Column("bucket_start", sa.DateTime(timezone=True), nullable=False),
+ sa.Column("client_id", sa.Text(), nullable=False),
+ sa.Column("model", sa.Text(), nullable=False),
+ sa.Column("amount", sa.BigInteger(), nullable=False),
+ sa.ForeignKeyConstraint(
+ ["tenant_id"], ["tenants.id"], name="fk_tenant_usage_tenant"
+ ),
+ sa.PrimaryKeyConstraint(
+ "tenant_id", "metric", "bucket_start", "client_id", "model"
+ ),
+ sa.CheckConstraint(
+ "metric IN ('messages', 'turns', 'input_tokens', 'output_tokens')",
+ name="ck_tenant_usage_metric",
+ ),
+ sa.CheckConstraint("amount > 0", name="ck_tenant_usage_amount"),
+ )
+ op.execute('ALTER TABLE "tenant_usage" ENABLE ROW LEVEL SECURITY')
+ op.execute(_CREATE_POLICY)
+
+
+def downgrade() -> None:
+ op.execute(f'DROP POLICY IF EXISTS {POLICY_NAME} ON "tenant_usage"')
+ op.drop_table("tenant_usage")
diff --git a/core/switch_core/session_activity/service.py b/core/switch_core/session_activity/service.py
index 9c9793090..d52e4f49f 100644
--- a/core/switch_core/session_activity/service.py
+++ b/core/switch_core/session_activity/service.py
@@ -16,6 +16,7 @@ from dataclasses import dataclass
from datetime import UTC, datetime, timedelta
from typing import Any, Literal
+from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from switch_core.addressing import allows_on_behalf_of, parse_policy
@@ -25,6 +26,7 @@ from switch_core.db.models import (
Agent,
ApprovalRequest,
SessionActivityItem,
+ UsageMetric,
require_tenant_id,
)
from switch_core.db.session_scope import tenant_session
@@ -38,6 +40,7 @@ from switch_core.db.stores.session_activity_store import (
ApprovalRequestStore,
SessionActivityStore,
)
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.delivery.addressing import AddressingResolver
from switch_core.sessions.contract import (
ApprovalResult,
@@ -133,6 +136,7 @@ class SessionActivityService:
self._sessions = session_factory
self._approvals = ApprovalRequestStore()
self._activity = SessionActivityStore()
+ self._usage = UsageStore()
self._rooms = RoomStore()
self._external_users = ExternalUserStore()
self._addressing = AddressingResolver(
@@ -197,7 +201,13 @@ class SessionActivityService:
async with tenant_session(self._sessions, tenant_id) as db, db.begin():
if room_id is not None:
await self._require_member(db, agent_id, room_id)
- return await self._activity.upsert(
+ first_report = kind == "turn" and (
+ await self._activity.status_for_update(
+ db, agent_id, session_id, turn_id, item_id
+ )
+ is None
+ )
+ moved = await self._activity.upsert(
db,
SessionActivityItem(
tenant_id=tenant_id,
@@ -217,6 +227,36 @@ class SessionActivityService:
occurred_at=occurred_at,
),
)
+ if moved and first_report:
+ await self._meter_turn(db, tenant_id, agent_id)
+ return moved
+
+ async def _meter_turn(
+ self, db: AsyncSession, tenant_id: str, agent_id: str
+ ) -> None:
+ """Count a turn the first time its host reports it, whatever its status.
+
+ A turn has been paid for once it exists: one that errors or is
+ interrupted still spent the model's time, so counting only the ones
+ that complete would under-report exactly the runaway loops a budget is
+ for. Charged to the agent's client, the identity every other metric is
+ counted against.
+ """
+ client_id = await db.scalar(
+ select(Agent.client_id).where(
+ Agent.tenant_id == tenant_id, Agent.id == agent_id
+ )
+ )
+ if client_id is None:
+ raise SessionError("NOT_FOUND", f"Agent {agent_id} does not exist.")
+ await self._usage.record(
+ db,
+ tenant_id=tenant_id,
+ metric=UsageMetric.TURNS,
+ client_id=client_id,
+ model="",
+ amount=1,
+ )
async def turn_items(
self, agent_id: str, session_id: str, turn_id: str
diff --git a/core/switch_core/transport/postgres.py b/core/switch_core/transport/postgres.py
index 281134861..2b11c27ca 100644
--- a/core/switch_core/transport/postgres.py
+++ b/core/switch_core/transport/postgres.py
@@ -41,7 +41,13 @@ from datetime import UTC, datetime
from typing import TYPE_CHECKING, Any
from switch_core.attachments import ATTACHMENT_GROUP_KEY
-from switch_core.db.models import ClientRoom, MediaBlob, Message, MessageAttachment
+from switch_core.db.models import (
+ ClientRoom,
+ MediaBlob,
+ Message,
+ MessageAttachment,
+ UsageMetric,
+)
from switch_core.db.session_scope import tenant_session
from switch_core.logging_context import log_context
from switch_core.messages.recorded_types import EPHEMERAL
@@ -80,6 +86,7 @@ if TYPE_CHECKING:
from switch_core.db.stores.media_store import MediaStore
from switch_core.db.stores.message_store import MessageStore
from switch_core.db.stores.room_store import RoomStore
+ from switch_core.db.stores.usage_store import UsageStore
from switch_core.messages.notify import MessageListener
logger = logging.getLogger(__name__)
@@ -93,6 +100,12 @@ _DELIVERY_PAGE = 200
_MEDIA_MSGTYPES = frozenset({"m.image", "m.file", "m.video", "m.audio"})
+# What a tenant is metered for: something a participant said. Custom events
+# are the platform's own bookkeeping — reports, state, receipts — and charging
+# a tenant for them would bill it for how Switch works.
+_METERED_KINDS = frozenset({"message", "media"})
+
+
def _sent_kind(event_type: str, content: dict[str, object]) -> str:
"""A bounded label for what was sent.
@@ -161,6 +174,7 @@ class PostgresTransport:
session_factory: async_sessionmaker[AsyncSession],
room_store: RoomStore,
message_store: MessageStore,
+ usage_store: UsageStore,
media_store: MediaStore,
listener: MessageListener,
invites: InviteBus,
@@ -186,6 +200,7 @@ class PostgresTransport:
self._session_factory = session_factory
self._room_store = room_store
self._message_store = message_store
+ self._usage_store = usage_store
self._media_store = media_store
self._listener = listener
self._invites = invites
@@ -685,6 +700,15 @@ class PostgresTransport:
await self._message_store.create(
session, message, attachments_in(content)
)
+ if kind in _METERED_KINDS:
+ await self._usage_store.record(
+ session,
+ tenant_id=tenant_id,
+ metric=UsageMetric.MESSAGES,
+ client_id=self.client_id,
+ model="",
+ amount=1,
+ )
await session.commit()
except Exception:
# `MESSAGES_SENT` is recorded only after the commit, so without
diff --git a/core/tests/integration/conftest.py b/core/tests/integration/conftest.py
index 001c21e81..cc95737b2 100644
--- a/core/tests/integration/conftest.py
+++ b/core/tests/integration/conftest.py
@@ -76,6 +76,7 @@ from switch_core.db.stores.room_role_store import RoomRoleStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.task_store import TaskStore
from switch_core.db.stores.tenant_store import TenantStore
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.db.stores.user_store import UserStore
from switch_core.main import _seed_agent_registration_bootstrap_key
from switch_core.messages.notify import MessageListener
@@ -557,6 +558,7 @@ async def harness(session_env: SessionEnv) -> AsyncIterator[Harness]:
config=config,
room_store=session_env.room_store,
message_store=session_env.message_store,
+ usage_store=UsageStore(),
media_store=session_env.media_store,
listener=message_listener,
invites=invites,
diff --git a/core/tests/switch_core/clients/test_client_tenant_plumbing.py b/core/tests/switch_core/clients/test_client_tenant_plumbing.py
index 09d217977..f14b7969a 100644
--- a/core/tests/switch_core/clients/test_client_tenant_plumbing.py
+++ b/core/tests/switch_core/clients/test_client_tenant_plumbing.py
@@ -47,6 +47,7 @@ from switch_core.db.stores.media_store import MediaStore
from switch_core.db.stores.message_store import MessageStore
from switch_core.db.stores.room_store import RoomStore
from switch_core.db.stores.tenant_store import TenantStore
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.tenant_context import tenant_scope
from switch_core.transport.ephemeral import EphemeralBus
from switch_core.transport.invites import InviteBus
@@ -59,6 +60,7 @@ def _factory(session_factory: async_sessionmaker[AsyncSession]) -> ClientFactory
config=SimpleNamespace(matrix_server_name="test"), # type: ignore[arg-type]
room_store=RoomStore(),
message_store=MessageStore(),
+ usage_store=UsageStore(),
media_store=MediaStore(),
listener=MagicMock(),
invites=InviteBus(),
diff --git a/core/tests/switch_core/db/stores/test_usage_store.py b/core/tests/switch_core/db/stores/test_usage_store.py
new file mode 100644
index 000000000..ecdf9c8f5
--- /dev/null
+++ b/core/tests/switch_core/db/stores/test_usage_store.py
@@ -0,0 +1,194 @@
+"""Per-tenant usage counters, against a real database.
+
+The upsert, the hour bucket and the check constraints are the behaviour, so
+none of this is mocked.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from switch_core.db.models import (
+ TENANT_ZERO_ID,
+ Client,
+ Tenant,
+ TenantUsage,
+ UsageMetric,
+)
+from switch_core.db.session_scope import tenant_session
+from switch_core.db.stores.usage_store import UsageStore
+
+OTHER_TENANT = "11111111-1111-1111-1111-111111111111"
+
+
+async def _client(session: AsyncSession, name: str) -> str:
+ client = Client(matrix_user_id=f"@{name}:test", display_name=name, type="agent")
+ session.add(client)
+ await session.flush()
+ return client.id
+
+
+async def _record(
+ session: AsyncSession,
+ client_id: str,
+ *,
+ metric: UsageMetric = UsageMetric.MESSAGES,
+ model: str = "",
+ amount: int = 1,
+ tenant_id: str = TENANT_ZERO_ID,
+) -> None:
+ await UsageStore().record(
+ session,
+ tenant_id=tenant_id,
+ metric=metric,
+ client_id=client_id,
+ model=model,
+ amount=amount,
+ )
+
+
+def _hour(offset: int) -> datetime:
+ now = datetime.now(UTC).replace(minute=0, second=0, microsecond=0)
+ return now + timedelta(hours=offset)
+
+
+class TestRecording:
+ async def test_counts_in_the_same_hour_add_up(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ client_id = await _client(session, "counted")
+ await _record(session, client_id)
+ await _record(session, client_id, amount=4)
+ await session.commit()
+
+ async with session_factory() as session:
+ rows = (await session.scalars(select(TenantUsage))).all()
+
+ assert len(rows) == 1
+ assert rows[0].amount == 5
+ assert rows[0].bucket_start == _hour(0)
+
+ async def test_metrics_and_models_are_counted_apart(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ client_id = await _client(session, "several")
+ await _record(session, client_id)
+ await _record(session, client_id, metric=UsageMetric.TURNS)
+ await _record(
+ session, client_id, metric=UsageMetric.INPUT_TOKENS, model="a"
+ )
+ await _record(
+ session, client_id, metric=UsageMetric.INPUT_TOKENS, model="b"
+ )
+ await session.commit()
+
+ async with session_factory() as session:
+ count = await session.scalar(select(func.count()).select_from(TenantUsage))
+
+ assert count == 4
+
+ async def test_a_count_that_is_not_positive_is_refused(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ # A zero or negative amount would let a caller spend usage back, so it
+ # is an error at the door rather than an adjustment.
+ async with session_factory() as session:
+ client_id = await _client(session, "refused")
+ with pytest.raises(ValueError, match="positive"):
+ await _record(session, client_id, amount=0)
+
+ async def test_the_database_refuses_an_unknown_metric(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ session.add(
+ TenantUsage(
+ metric="vibes",
+ bucket_start=_hour(0),
+ client_id="c",
+ model="",
+ amount=1,
+ )
+ )
+ with pytest.raises(IntegrityError, match="ck_tenant_usage_metric"):
+ await session.flush()
+
+
+class TestTotals:
+ async def test_totals_cover_the_hours_in_the_window(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ client_id = await _client(session, "windowed")
+ for offset, amount in ((-3, 100), (-2, 10), (-1, 1), (0, 1000)):
+ session.add(
+ TenantUsage(
+ metric="messages",
+ bucket_start=_hour(offset),
+ client_id=client_id,
+ model="",
+ amount=amount,
+ )
+ )
+ await session.commit()
+
+ async with session_factory() as session:
+ # `since` mid-hour still takes that whole hour; `until` excludes
+ # the bucket that starts on it.
+ totals = await UsageStore().totals(
+ session,
+ tenant_id=TENANT_ZERO_ID,
+ since=_hour(-2) + timedelta(minutes=30),
+ until=_hour(0),
+ )
+
+ assert [(t.metric, t.client_name, t.amount) for t in totals] == [
+ ("messages", "windowed", 11)
+ ]
+
+ async def test_usage_outlives_the_client_it_names(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ # What a deleted client spent is still the tenant's spend.
+ async with session_factory() as session:
+ await _record(session, "gone-client")
+ await session.commit()
+
+ async with session_factory() as session:
+ totals = await UsageStore().totals(
+ session, tenant_id=TENANT_ZERO_ID, since=_hour(-1), until=_hour(1)
+ )
+
+ assert len(totals) == 1
+ assert totals[0].client_id == "gone-client"
+ assert totals[0].client_name is None
+ assert totals[0].amount == 1
+
+ async def test_another_tenants_usage_is_not_counted(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ # The owner connection ignores the policy, so this is the explicit
+ # tenant filter doing the work — the one a fan-out relies on.
+ async with session_factory() as session:
+ session.add(Tenant(id=OTHER_TENANT, slug="other", name="Other"))
+ await session.commit()
+ async with tenant_session(session_factory, OTHER_TENANT) as session:
+ await _record(session, "theirs", amount=50, tenant_id=OTHER_TENANT)
+ await session.commit()
+ async with session_factory() as session:
+ await _record(session, "ours", amount=2)
+ await session.commit()
+
+ async with session_factory() as session:
+ totals = await UsageStore().totals(
+ session, tenant_id=TENANT_ZERO_ID, since=_hour(-1), until=_hour(1)
+ )
+
+ assert [(t.client_id, t.amount) for t in totals] == [("ours", 2)]
diff --git a/core/tests/switch_core/session_activity/test_service.py b/core/tests/switch_core/session_activity/test_service.py
index 2ae265892..763703e09 100644
--- a/core/tests/switch_core/session_activity/test_service.py
+++ b/core/tests/switch_core/session_activity/test_service.py
@@ -3,10 +3,10 @@ from __future__ import annotations
from datetime import UTC, datetime, timedelta
import pytest
-from sqlalchemy import update
+from sqlalchemy import select, update
from switch_core.addressing import owner_only_policy
-from switch_core.db.models import ApprovalRequest
+from switch_core.db.models import ApprovalRequest, TenantUsage
from switch_core.session_activity.service import (
ApprovalOption,
PlatformPerson,
@@ -118,6 +118,39 @@ async def test_a_step_is_upserted_by_revision_and_announced_by_turn(service, cha
assert all(change.row is None for change in announced)
+def _turn(turn_id: str, revision: int, status: str):
+ return _step(
+ turn_id=turn_id,
+ item_id="turn",
+ kind="turn",
+ revision=revision,
+ status=status,
+ title="",
+ text="",
+ )
+
+
+async def _turns_counted(session_factory) -> int:
+ async with session_factory() as db:
+ rows = await db.scalars(
+ select(TenantUsage.amount).where(TenantUsage.metric == "turns")
+ )
+ return sum(rows)
+
+
+async def test_a_turn_is_counted_once_when_first_reported(service, session_factory):
+ # A turn is spent once it exists: its later statuses, a retried report and
+ # its steps are the same turn, and one that errors still cost model time.
+ await service.report_item(AGENT, SESSION, **_turn("turn-1", 1, "running"))
+ await service.report_item(AGENT, SESSION, **_turn("turn-1", 1, "running"))
+ await service.report_item(AGENT, SESSION, **_step(revision=2))
+ await service.report_item(AGENT, SESSION, **_turn("turn-1", 3, "error"))
+ assert await _turns_counted(session_factory) == 1
+
+ await service.report_item(AGENT, SESSION, **_turn("turn-2", 4, "completed"))
+ assert await _turns_counted(session_factory) == 2
+
+
async def test_a_turns_steps_are_read_in_the_order_first_reported(service):
for item_id, kind, status in [
("turn", "turn", "running"),
diff --git a/core/tests/switch_core/transport/test_postgres_transport.py b/core/tests/switch_core/transport/test_postgres_transport.py
index a69c36a5d..c4ebf8bda 100644
--- a/core/tests/switch_core/transport/test_postgres_transport.py
+++ b/core/tests/switch_core/transport/test_postgres_transport.py
@@ -17,15 +17,24 @@ import uuid
from collections.abc import Iterator
import pytest
+from sqlalchemy import delete, select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
-from switch_core.db.models import TENANT_ZERO_ID, Client, ClientRoom, Room, Tenant
+from switch_core.db.models import (
+ TENANT_ZERO_ID,
+ Client,
+ ClientRoom,
+ Room,
+ Tenant,
+ TenantUsage,
+)
from switch_core.db.session_scope import tenant_session
from switch_core.db.stores.client_store import ClientStore
from switch_core.db.stores.media_store import MediaStore
from switch_core.db.stores.message_store import MessageStore
from switch_core.db.stores.room_store import RoomStore
+from switch_core.db.stores.usage_store import UsageStore
from switch_core.observability.metrics import MetricsRegistry, install, uninstall
from switch_core.provisioning.postgres import PostgresProvisioning
from switch_core.tenant_context import current_tenant_id, tenant_scope
@@ -185,6 +194,7 @@ def _transport(
session_factory=session_factory,
room_store=RoomStore(),
message_store=MessageStore(),
+ usage_store=UsageStore(),
media_store=MediaStore(),
listener=listener or _FakeListener(),
invites=invites or InviteBus(),
@@ -200,6 +210,72 @@ class TestConformsToThePort:
assert isinstance(transport, MessageTransport)
+class TestMetering:
+ """Every message a participant sends is counted against its tenant, in the
+ same write as the message, so the two cannot disagree."""
+
+ async def _usage(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> list[tuple[str, str, int]]:
+ async with session_factory() as session:
+ rows = await session.scalars(select(TenantUsage))
+ return [(r.metric, r.client_id, r.amount) for r in rows]
+
+ async def test_messages_and_media_are_counted_for_the_sender(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ async with session_factory() as session:
+ _, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ await transport.send_message(transport_room_id, "one", sender_name="a")
+ await transport.send_message(transport_room_id, "two", sender_name="a")
+ await transport.send_media(
+ transport_room_id,
+ "blob://1",
+ "report.pdf",
+ "application/pdf",
+ 2048,
+ sender_name="a",
+ msgtype="m.file",
+ )
+
+ assert await self._usage(session_factory) == [("messages", client_id, 3)]
+
+ async def test_platform_events_are_not_counted(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ # Reports, runtime state and receipts are how Switch works, not
+ # something the tenant said, so they are not billed as messages.
+ async with session_factory() as session:
+ _, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ await transport.send_event(
+ transport_room_id, "com.switch.report.tool_call", {"tool": "Bash"}
+ )
+
+ assert await self._usage(session_factory) == []
+
+ async def test_the_count_survives_the_room(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ # Deleting a room cascades to its messages; it must not refund them.
+ async with session_factory() as session:
+ room_id, transport_room_id, client_id, user_id = await _make_room(session)
+ await session.commit()
+
+ transport = _transport(session_factory, client_id=client_id, user_id=user_id)
+ await transport.send_message(transport_room_id, "spent", sender_name="a")
+ async with session_factory() as session:
+ await session.execute(delete(Room).where(Room.id == room_id))
+ await session.commit()
+
+ assert await self._usage(session_factory) == [("messages", client_id, 1)]
+
+
class TestSending:
async def test_a_message_becomes_a_row(
self, session_factory: async_sessionmaker[AsyncSession]
@@ -455,6 +531,7 @@ class TestMedia:
session_factory=session_factory,
room_store=RoomStore(),
message_store=MessageStore(),
+ usage_store=UsageStore(),
media_store=MediaStore(),
listener=_FakeListener(),
invites=InviteBus(),