Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
feat(metering): usage budgets that stop an agent once it has spent them
Petr Bauch128df5a34216
diff --git a/core/switch_core/bridges/agent/api/handlers.py b/core/switch_core/bridges/agent/api/handlers.pyindex 8c16ba2ec..1b05075ce 100644--- a/core/switch_core/bridges/agent/api/handlers.py+++ b/core/switch_core/bridges/agent/api/handlers.py@@ -105,6 +105,7 @@ from switch_core.bridges.agent.registration_bootstrap import (REGISTRATION_KEY_TYPES,resolve_registration_owner_id,)+from switch_core.budgets import BudgetExceededfrom switch_core.db.models import Agent, Taskfrom switch_core.db.stores.api_key_store import ApiKeyStorefrom switch_core.db.stores.feature_flag_store import FeatureFlagStore@@ -463,6 +464,8 @@ async def send_message(logger.debug("Recieved message from agent %s: %s", agent.name, req.content)try:event_id = await protocol.send_message(agent.id, req.room_id, req.content)+ except BudgetExceeded as e:+ raise HTTPException(status_code=429, detail=str(e)) from eexcept ValueError as e:raise HTTPException(status_code=404, detail=str(e)) from eexcept PermissionError as e:@@ -549,6 +552,8 @@ async def upload_media(caption=caption,thread_id=thread_id,)+ except BudgetExceeded as e:+ raise HTTPException(status_code=429, detail=str(e)) from eexcept ValueError as e:raise HTTPException(status_code=400, detail=str(e)) from eexcept PermissionError as e:@@ -1297,6 +1302,8 @@ async def delegate_task(description=req.description,)task = await protocol.get_task(agent.id, result.task_id)+ except BudgetExceeded as e:+ raise HTTPException(status_code=429, detail=str(e)) from eexcept ValueError as e:raise HTTPException(status_code=404, detail=str(e)) from eexcept PermissionError as e:diff --git a/core/switch_core/bridges/agent/api/operations.py b/core/switch_core/bridges/agent/api/operations.pyindex af547f55f..53fc928c9 100644--- a/core/switch_core/bridges/agent/api/operations.py+++ b/core/switch_core/bridges/agent/api/operations.py@@ -34,6 +34,7 @@ from switch_core.bridges.agent.operations.callctx import ()from switch_core.bridges.agent.protocol.connections import UnknownConnectionErrorfrom switch_core.bridges.agent.protocol.service import ProtocolService+from switch_core.budgets import BudgetExceededfrom switch_core.db.models import Agentlogger = logging.getLogger(__name__)@@ -238,6 +239,8 @@ async def post_operation(raise HTTPException(status_code=404, detail=str(exc)) from excexcept BadArgumentsError as exc:raise HTTPException(status_code=400, detail=str(exc)) from exc+ except BudgetExceeded as exc:+ raise HTTPException(status_code=429, detail=str(exc)) from excexcept PermissionError as exc:raise HTTPException(status_code=403, detail=str(exc)) from excexcept ValueError as exc:diff --git a/core/switch_core/bridges/agent/protocol/service.py b/core/switch_core/bridges/agent/protocol/service.pyindex 6e12350b9..17804816d 100644--- a/core/switch_core/bridges/agent/protocol/service.py+++ b/core/switch_core/bridges/agent/protocol/service.py@@ -58,6 +58,7 @@ from switch_core.bridges.agent.registration_bootstrap import (resolve_registration_owner_id,)from switch_core.bridges.resource.service import ResourceService+from switch_core.budgets import BudgetGuardfrom switch_core.clients.admin_messages import PLATFORM_MARKER as _PLATFORM_MARKERfrom switch_core.clients.admin_messages import (platform_on_behalf_of,@@ -79,6 +80,7 @@ from switch_core.db.models import (Task,Tool,User,+ require_tenant_id,)from switch_core.db.session_scope import tenant_sessionfrom switch_core.db.stores.agent_runtime_state_store import (@@ -87,6 +89,7 @@ from switch_core.db.stores.agent_runtime_state_store import (from switch_core.db.stores.agent_runtime_state_store import (AgentRuntimeStateStore,)+from switch_core.db.stores.budget_store import BudgetStorefrom switch_core.db.stores.message_store import MessageStorefrom switch_core.db.stores.room_group_store import RoomGroupStorefrom switch_core.db.stores.room_role_store import RoomRoleStore@@ -288,6 +291,7 @@ class ProtocolService:self.room_role_store = RoomRoleStore()self.room_group_store = RoomGroupStore()self.message_store = MessageStore()+ self.budget_guard = BudgetGuard(BudgetStore())self.user_store = UserStore()self.room_store = room_storeself.room_service = room_service@@ -992,9 +996,23 @@ class ProtocolService:async def require_room_member(self, agent_id: str, room_id: str) -> RoomDescriptor:"""Get room and verify agent is a member. Raises PermissionError if not."""async with self.session_factory() as session:- found = await self.room_store.get_with_membership(- session, room_id, agent_id+ return await self._room_member_in(session, agent_id, room_id)++ async def require_room_poster(self, agent_id: str, room_id: str) -> RoomDescriptor:+ """`require_room_member`, and raise `BudgetExceeded` if the agent has+ reached a budget covering it. One session for both, so a post still+ costs one pool checkout."""+ async with self.session_factory() as session:+ room = await self._room_member_in(session, agent_id, room_id)+ await self.budget_guard.require_within(+ session, tenant_id=require_tenant_id(), agent_id=agent_id)+ return room++ async def _room_member_in(+ self, session: AsyncSession, agent_id: str, room_id: str+ ) -> RoomDescriptor:+ found = await self.room_store.get_with_membership(session, room_id, agent_id)if found is None:raise ValueError(f"Room not found: {room_id}")room, is_member = found@@ -1195,7 +1213,7 @@ class ProtocolService:logger.debug("[AGENT-MSG] agent=%s room=%s content=%s", agent_id, room_id, content[:80])- room = await self.require_room_member(agent_id, room_id)+ room = await self.require_room_poster(agent_id, room_id)client = self.client_lifecycle.get_by_agent_id(agent_id)if client is None:raise ValueError("Agent client not running")@@ -1270,7 +1288,7 @@ class ProtocolService:f"attachment '{filename}' is {len(data)} bytes, over the "f"{max_bytes}-byte limit (AGENT_MEDIA_MAX_BYTES)")- room = await self.require_room_member(agent_id, room_id)+ room = await self.require_room_poster(agent_id, room_id)client = self.client_lifecycle.get_by_agent_id(agent_id)if client is None:raise ValueError("Agent client not running")@@ -2151,9 +2169,10 @@ class ProtocolService:"""Delegate a task from one agent to another.Returns task_id and the performer's reachability status at delegation time.- Raises ValueError if agents or room not found, or agents not in room.+ Raises ValueError if agents or room not found, or agents not in room,+ and `BudgetExceeded` if either agent has reached a budget covering it."""- room = await self.require_room_member(requester_id, room_id)+ room = await self.require_room_poster(requester_id, room_id)async with self.session_factory() as session:performer = await self.agent_store.get(session, performer_id)@@ -2175,6 +2194,9 @@ class ProtocolService:group_id=room_row.group_id if room_row is not None else None,sender_agent_id=requester_id,)+ await self.budget_guard.require_within(+ session, tenant_id=require_tenant_id(), agent_id=performer_id+ )async with self.session_factory() as session:task = Task(diff --git a/core/switch_core/budgets.py b/core/switch_core/budgets.pynew file mode 100644index 000000000..58bc94938--- /dev/null+++ b/core/switch_core/budgets.py@@ -0,0 +1,63 @@+"""The one check every path an agent spends through makes before it spends.++An agent that has reached a budget covering it is stopped until the period+turns over: addressed room messages are answered with a refusal instead of+delivered (so no session is started or prompted for them), and its own posts+are refused. People are never stopped — a budget caps what agents spend.++What a person types into a session from Switch Console goes straight to the+session's host and never passes through Switch, so it is not stopped here.++Usage is counted after the fact (a turn's tokens arrive when it ends), so the+check stops the next piece of work, not the one in flight, and a budget can be+overshot by whatever was already running when it was reached.+"""++from sqlalchemy.ext.asyncio import AsyncSession++from switch_core.db.stores.budget_store import BudgetStanding, BudgetStore+++def _describe(standing: BudgetStanding) -> str:+ whose = (+ f"Agent {standing.agent_name}"+ if standing.agent_name is not None+ else "This workspace"+ )+ metric = standing.metric.replace("_", " ")+ model = f" on {standing.model}" if standing.model else ""+ resets = standing.resets_at.strftime("%Y-%m-%d %H:%M UTC")+ return (+ f"{whose} has reached its budget of {standing.amount_limit:,} {metric}"+ f"{model} per {standing.period_hours}h. It resets at {resets}."+ )+++class BudgetExceeded(Exception):+ """An agent has reached a budget covering it. The message is written for+ the people in the room, since they are who see it."""++ def __init__(self, standing: BudgetStanding) -> None:+ super().__init__(_describe(standing))+ self.standing = standing+++class BudgetGuard:+ def __init__(self, store: BudgetStore) -> None:+ self._store = store++ async def require_within(+ self, session: AsyncSession, *, tenant_id: str, agent_id: str+ ) -> None:+ """Raise `BudgetExceeded` if the agent has reached any budget covering+ it. When several have, the one that resets last is reported, because+ that is how long the agent is actually stopped for."""+ exhausted = [+ standing+ for standing in await self._store.standings(+ session, tenant_id=tenant_id, agent_id=agent_id+ )+ if standing.exhausted+ ]+ if exhausted:+ raise BudgetExceeded(max(exhausted, key=lambda s: s.resets_at))diff --git a/core/switch_core/clients/agent_client.py b/core/switch_core/clients/agent_client.pyindex 7d3c15f26..f1968c74a 100644--- a/core/switch_core/clients/agent_client.py+++ b/core/switch_core/clients/agent_client.py@@ -33,6 +33,7 @@ from switch_core.bridges.agent.protocol.types import (TaskFinalisePayload,TaskUpdatePayload,)+from switch_core.budgets import BudgetExceeded, BudgetGuardfrom switch_core.clients.admin_messages import (PLATFORM_MARKER,platform_on_behalf_of,@@ -57,6 +58,7 @@ from switch_core.db.models import Agentfrom switch_core.db.session_scope import tenant_sessionfrom switch_core.db.stores.agent_session_store import AgentSessionStorefrom switch_core.db.stores.agent_store import AgentStore+from switch_core.db.stores.budget_store import BudgetStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.document_store import DocumentStorefrom switch_core.db.stores.external_user_store import ExternalUserStore@@ -276,6 +278,7 @@ class AgentClient(ClientBase[ClientConfig]):external_user_store=external_user_store,live_connection_ids=connections.live_connection_ids,)+ self._budget_guard = BudgetGuard(BudgetStore())self._room_meta: dict[str, RoomMeta | None] = {}# In-flight multi-attachment groups, by group id, with their safety-net# timers. Both are cleared when a group completes or times out, so a@@ -1330,8 +1333,8 @@ class AgentClient(ClientBase[ClientConfig]):) -> _GateOutcome:"""Apply the scoped addressing policy to a message that tags this agent.- When the sender is not permitted by the agent's policy, the message is- demoted to unaddressed room chatter and the caller is handed a refusal+ When the sender is not permitted by the agent's policy, or the agent+ has reached a budget covering it, the message is demoted to unaddressed room chatter and the caller is handed a refusalto post (once, guarded by AUTO_REPLY_FLAG so two agents can'tping-pong). Zero cost for the common case: only messages that alreadytag this agent are ever checked, and open policies short-circuit.@@ -1340,10 +1343,19 @@ class AgentClient(ClientBase[ClientConfig]):session, agent, event.sender, meta.room_id, event.content)if decision.allowed:- return _GateOutcome(addressed=True, refusal=None)+ try:+ await self._budget_guard.require_within(+ session, tenant_id=self.tenant_id, agent_id=agent.id+ )+ except BudgetExceeded as exc:+ refusal = str(exc)+ else:+ return _GateOutcome(addressed=True, refusal=None)+ else:+ refusal = decision.refusalif self._triggered_by_auto_reply(event):return _GateOutcome(addressed=False, refusal=None)- return _GateOutcome(addressed=False, refusal=decision.refusal)+ return _GateOutcome(addressed=False, refusal=refusal)@staticmethoddef _triggered_by_auto_reply(event: InboundMessage) -> bool:diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.pyindex 59b3c646d..28be83933 100644--- a/core/switch_core/db/models.py+++ b/core/switch_core/db/models.py@@ -2362,6 +2362,75 @@ class TenantUsage(TenantScoped, Base):amount: Mapped[int] = mapped_column(BigInteger, nullable=False)+# A budget's period is at most a leap year, and its limit at most the largest+# integer a JavaScript client reads exactly. Both keep the period arithmetic+# and the gateway's numbers from overflowing.+MAX_BUDGET_PERIOD_HOURS = 8784+MAX_BUDGET_AMOUNT = 2**53 - 1+++class UsageBudget(TenantScoped, Base):+ """A ceiling on one metric over a repeating period.++ `agent_id` null covers every agent in the tenant; otherwise the one agent.+ `model` empty covers every model. An agent that has reached any budget+ covering it is stopped until the period turns over; people are never+ stopped. A tenant with no budgets is unlimited.++ Periods are whole hours counted from the Unix epoch in UTC, so a daily+ budget turns over at midnight UTC and every writer agrees when.+ """++ __tablename__ = "usage_budgets"+ __table_args__ = (+ ForeignKeyConstraint(+ ["tenant_id", "agent_id"],+ ["agents.tenant_id", "agents.id"],+ name="fk_usage_budgets_agent",+ ondelete="CASCADE",+ ),+ CheckConstraint(+ "metric IN ({})".format(", ".join(f"'{m}'" for m in UsageMetric)),+ name="ck_usage_budgets_metric",+ ),+ CheckConstraint(+ f"amount_limit > 0 AND amount_limit <= {MAX_BUDGET_AMOUNT}",+ name="ck_usage_budgets_amount_limit",+ ),+ CheckConstraint(+ f"period_hours > 0 AND period_hours <= {MAX_BUDGET_PERIOD_HOURS}",+ name="ck_usage_budgets_period_hours",+ ),+ Index(+ "uq_usage_budgets_tenant_wide",+ "tenant_id",+ "metric",+ "model",+ unique=True,+ postgresql_where=text("agent_id IS NULL"),+ ),+ Index(+ "uq_usage_budgets_agent",+ "tenant_id",+ "agent_id",+ "metric",+ "model",+ unique=True,+ postgresql_where=text("agent_id IS NOT NULL"),+ ),+ )++ id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)+ agent_id: Mapped[str | None] = mapped_column(Text, nullable=True)+ metric: Mapped[str] = mapped_column(Text, nullable=False)+ model: Mapped[str] = mapped_column(Text, nullable=False)+ amount_limit: Mapped[int] = mapped_column(BigInteger, nullable=False)+ period_hours: Mapped[int] = mapped_column(Integer, nullable=False)+ created_at: Mapped[datetime] = mapped_column(+ DateTime(timezone=True), server_default=func.now(), 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 thisdiff --git a/core/switch_core/db/stores/budget_store.py b/core/switch_core/db/stores/budget_store.pynew file mode 100644index 000000000..12cb9aaba--- /dev/null+++ b/core/switch_core/db/stores/budget_store.py@@ -0,0 +1,186 @@+from dataclasses import dataclass+from datetime import datetime++from sqlalchemy import BigInteger, ColumnElement, and_, cast, delete, func, or_, select+from sqlalchemy.ext.asyncio import AsyncSession+from sqlalchemy.orm import aliased++from switch_core.db.models import Agent, TenantUsage, UsageBudget, UsageMetric+++@dataclass(frozen=True)+class BudgetStanding:+ """A budget and what has been spent against it in the current period.++ `agent_id` and `agent_name` are null for a budget covering every agent.+ """++ id: str+ agent_id: str | None+ agent_name: str | None+ metric: str+ model: str+ amount_limit: int+ period_hours: int+ spent: int+ resets_at: datetime++ @property+ def exhausted(self) -> bool:+ return self.spent >= self.amount_limit+++class BudgetNotFound(LookupError):+ pass+++def _period_start() -> ColumnElement[datetime]:+ """The start of the budget's current period, on the database's clock.++ Periods are counted from the Unix epoch in whole hours, which puts a daily+ boundary at midnight UTC and lines every period up with the hourly usage+ buckets it sums.+ """+ seconds = cast(UsageBudget.period_hours, BigInteger) * 3600+ return func.to_timestamp(+ func.floor(func.extract("epoch", func.now()) / seconds) * seconds+ )+++class BudgetStore:+ async def standings(+ self, session: AsyncSession, *, tenant_id: str, agent_id: str | None+ ) -> list[BudgetStanding]:+ """The tenant's budgets with their current spend.++ With `agent_id`, only the budgets covering that agent: its own and the+ tenant-wide ones. Without, every budget the tenant has.++ A tenant-wide budget sums what the tenant's agents spent, not what its+ people and bridges did, since it is agents that a budget stops.++ Names the tenant explicitly as well as relying on the bound session,+ for the reason `UsageStore.totals` gives.+ """+ period_start = _period_start()+ agent_clients = aliased(Agent)+ spent = (+ select(func.coalesce(func.sum(TenantUsage.amount), 0))+ .where(+ TenantUsage.tenant_id == UsageBudget.tenant_id,+ TenantUsage.metric == UsageBudget.metric,+ TenantUsage.bucket_start >= period_start,+ or_(UsageBudget.model == "", TenantUsage.model == UsageBudget.model),+ or_(+ and_(+ UsageBudget.agent_id.is_(None),+ TenantUsage.client_id.in_(+ select(agent_clients.client_id).where(+ agent_clients.tenant_id == UsageBudget.tenant_id+ )+ ),+ ),+ TenantUsage.client_id == Agent.client_id,+ ),+ )+ .correlate(UsageBudget, Agent)+ .scalar_subquery()+ )+ statement = (+ select(+ UsageBudget,+ Agent.name,+ spent,+ period_start + func.make_interval(0, 0, 0, 0, UsageBudget.period_hours),+ )+ .outerjoin(+ Agent,+ and_(+ Agent.tenant_id == UsageBudget.tenant_id,+ Agent.id == UsageBudget.agent_id,+ ),+ )+ .where(UsageBudget.tenant_id == tenant_id)+ .order_by(+ UsageBudget.agent_id.nulls_first(),+ UsageBudget.metric,+ UsageBudget.model,+ )+ )+ if agent_id is not None:+ statement = statement.where(+ or_(UsageBudget.agent_id.is_(None), UsageBudget.agent_id == agent_id)+ )+ rows = await session.execute(statement)+ return [+ BudgetStanding(+ id=budget.id,+ agent_id=budget.agent_id,+ agent_name=agent_name,+ metric=budget.metric,+ model=budget.model,+ amount_limit=budget.amount_limit,+ period_hours=budget.period_hours,+ spent=int(amount),+ resets_at=resets_at,+ )+ for budget, agent_name, amount, resets_at in rows+ ]++ async def create(+ self,+ session: AsyncSession,+ *,+ tenant_id: str,+ agent_id: str | None,+ metric: UsageMetric,+ model: str,+ amount_limit: int,+ period_hours: int,+ ) -> UsageBudget:+ """Add a budget. A second budget on the same agent (or tenant-wide),+ metric and model fails on the unique index; the caller decides what+ that means to its user."""+ budget = UsageBudget(+ tenant_id=tenant_id,+ agent_id=agent_id,+ metric=metric.value,+ model=model,+ amount_limit=amount_limit,+ period_hours=period_hours,+ )+ session.add(budget)+ await session.flush()+ return budget++ async def update(+ self,+ session: AsyncSession,+ *,+ tenant_id: str,+ budget_id: str,+ amount_limit: int,+ period_hours: int,+ ) -> UsageBudget:+ budget = await session.scalar(+ select(UsageBudget).where(+ UsageBudget.tenant_id == tenant_id, UsageBudget.id == budget_id+ )+ )+ if budget is None:+ raise BudgetNotFound(budget_id)+ budget.amount_limit = amount_limit+ budget.period_hours = period_hours+ await session.flush()+ return budget++ async def delete(+ self, session: AsyncSession, *, tenant_id: str, budget_id: str+ ) -> None:+ result = await session.execute(+ delete(UsageBudget).where(+ UsageBudget.tenant_id == tenant_id, UsageBudget.id == budget_id+ )+ )+ if result.rowcount == 0: # type: ignore[attr-defined]+ raise BudgetNotFound(budget_id)diff --git a/core/switch_core/gateway/app.py b/core/switch_core/gateway/app.pyindex 9d57c4cb9..74de0ddba 100644--- a/core/switch_core/gateway/app.py+++ b/core/switch_core/gateway/app.py@@ -19,6 +19,7 @@ from switch_core.clients.client_lifecycle_service import ClientLifecycleServicefrom switch_core.config import SwitchConfigfrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.api_key_store import ApiKeyStore+from switch_core.db.stores.budget_store import BudgetStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom switch_core.db.stores.invitation_store import InvitationStore@@ -73,6 +74,7 @@ def create_gateway_app(invitation_store: InvitationStore,template_store: TemplateStore,usage_store: UsageStore,+ budget_store: BudgetStore,resource_service: ResourceService,protocol: ProtocolService,install_service: MessagingInstallService | None,@@ -96,6 +98,7 @@ def create_gateway_app(invitation_store=invitation_store,template_store=template_store,usage_store=usage_store,+ budget_store=budget_store,resource_service=resource_service,protocol=protocol,install_service=install_service,diff --git a/core/switch_core/gateway/dependencies.py b/core/switch_core/gateway/dependencies.pyindex 4b6098e96..d75ad0444 100644--- a/core/switch_core/gateway/dependencies.py+++ b/core/switch_core/gateway/dependencies.py@@ -21,6 +21,7 @@ from switch_core.clients.client_lifecycle_service import ClientLifecycleServicefrom switch_core.config import SwitchConfigfrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.api_key_store import ApiKeyStore+from switch_core.db.stores.budget_store import BudgetStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom switch_core.db.stores.invitation_store import InvitationStore@@ -57,6 +58,7 @@ def init_dependencies(invitation_store: InvitationStore,template_store: TemplateStore,usage_store: UsageStore,+ budget_store: BudgetStore,resource_service: ResourceService,protocol: ProtocolService,install_service: MessagingInstallService | None,@@ -79,6 +81,7 @@ def init_dependencies(_state["invitation_store"] = invitation_store_state["template_store"] = template_store_state["usage_store"] = usage_store+ _state["budget_store"] = budget_store_state["resource_service"] = resource_service_state["protocol"] = protocol_state["install_service"] = install_service@@ -201,6 +204,10 @@ def get_usage_store() -> UsageStore:return _state["usage_store"] # type: ignore[no-any-return]+def get_budget_store() -> BudgetStore:+ return _state["budget_store"] # type: ignore[no-any-return]++def get_connector_lifecycle() -> ServerSideConnectorLifecycleService:return _state["connector_lifecycle"] # type: ignore[no-any-return]diff --git a/core/switch_core/gateway/schemas.py b/core/switch_core/gateway/schemas.pyindex f3700dd5e..26901d9f2 100644--- a/core/switch_core/gateway/schemas.py+++ b/core/switch_core/gateway/schemas.py@@ -1,11 +1,17 @@from __future__ import annotations+from datetime import datetimefrom typing import Any, Literal-from pydantic import BaseModel, Field+from pydantic import BaseModel, Field, model_validatorfrom switch_core.addressing import AddressingPolicyfrom switch_core.bridges.collaboration.models import BridgeInstallLink+from switch_core.db.models import (+ MAX_BUDGET_AMOUNT,+ MAX_BUDGET_PERIOD_HOURS,+ UsageMetric,+)# ── Rooms ─────────────────────────────────────────────────────────────────────@@ -1190,3 +1196,44 @@ class TemplateValidateResponse(BaseModel):blocked: boolerrors: list[TemplateFinding]warnings: list[TemplateFinding]+++class BudgetCreateRequest(BaseModel):+ """A new budget. `agent_id` null covers every agent in the workspace;+ `model` empty covers every model."""++ agent_id: str | None+ metric: UsageMetric+ model: str+ amount_limit: int = Field(gt=0, le=MAX_BUDGET_AMOUNT)+ period_hours: int = Field(gt=0, le=MAX_BUDGET_PERIOD_HOURS)++ @model_validator(mode="after")+ def _model_only_on_token_metrics(self) -> BudgetCreateRequest:+ if self.model and self.metric in (UsageMetric.MESSAGES, UsageMetric.TURNS):+ raise ValueError(+ f"A {self.metric.value} budget cannot name a model: "+ f"{self.metric.value} are not counted per model"+ )+ return self+++class BudgetUpdateRequest(BaseModel):+ amount_limit: int = Field(gt=0, le=MAX_BUDGET_AMOUNT)+ period_hours: int = Field(gt=0, le=MAX_BUDGET_PERIOD_HOURS)+++class BudgetResponse(BaseModel):+ """A budget and what has been spent against it in the current period,+ which ends at `resets_at`."""++ id: str+ agent_id: str | None+ agent_name: str | None+ metric: str+ model: str+ amount_limit: int+ period_hours: int+ spent: int+ resets_at: datetime+ exhausted: booldiff --git a/core/switch_core/gateway/tenants.py b/core/switch_core/gateway/tenants.pyindex de91b37ce..a42bcf9c3 100644--- a/core/switch_core/gateway/tenants.py+++ b/core/switch_core/gateway/tenants.py@@ -18,6 +18,11 @@ from switch_core.db.models import Invitation, Tenant, TenantMember, Userfrom switch_core.db.session_scope import tenant_sessionfrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.api_key_store import ApiKeyStore+from switch_core.db.stores.budget_store import (+ BudgetNotFound,+ BudgetStanding,+ BudgetStore,+)from switch_core.db.stores.invitation_store import (InvitationNotUsableError,InvitationStore,@@ -41,6 +46,7 @@ from switch_core.gateway.dependencies import (current_telemetry,get_agent_store,get_api_key_store,+ get_budget_store,get_client_lifecycle,get_config,get_invitation_store,@@ -52,6 +58,9 @@ from switch_core.gateway.dependencies import (get_user_store,)from switch_core.gateway.schemas import (+ BudgetCreateRequest,+ BudgetResponse,+ BudgetUpdateRequest,InvitationAcceptRequest,InvitationCreateRequest,InvitationCreateResponse,@@ -470,6 +479,131 @@ async def get_usage(]+def _budget_response(standing: BudgetStanding) -> BudgetResponse:+ return BudgetResponse(+ id=standing.id,+ agent_id=standing.agent_id,+ agent_name=standing.agent_name,+ metric=standing.metric,+ model=standing.model,+ amount_limit=standing.amount_limit,+ period_hours=standing.period_hours,+ spent=standing.spent,+ resets_at=standing.resets_at,+ exhausted=standing.exhausted,+ )+++async def _budget_standing(+ session: AsyncSession, budget_store: BudgetStore, tenant_id: str, budget_id: str+) -> BudgetResponse:+ for standing in await budget_store.standings(+ session, tenant_id=tenant_id, agent_id=None+ ):+ if standing.id == budget_id:+ return _budget_response(standing)+ raise HTTPException(status_code=404, detail="Budget not found")++[email protected]("/tenants/{tenant_id}/budgets")+async def list_budgets(+ tenant_id: str,+ session: Annotated[AsyncSession, Depends(get_session)],+ budget_store: Annotated[BudgetStore, Depends(get_budget_store)],+ _user: Annotated[User, Depends(require_tenant_admin)],+) -> list[BudgetResponse]:+ """Every budget of the bound tenant with its spend in the current period.+ `owner`/`admin` only."""+ _require_bound_tenant(tenant_id)+ standings = await budget_store.standings(+ session, tenant_id=tenant_id, agent_id=None+ )+ return [_budget_response(s) for s in standings]++[email protected]("/tenants/{tenant_id}/budgets", status_code=201)+async def create_budget(+ tenant_id: str,+ body: BudgetCreateRequest,+ session: Annotated[AsyncSession, Depends(get_session)],+ budget_store: Annotated[BudgetStore, Depends(get_budget_store)],+ agent_store: Annotated[AgentStore, Depends(get_agent_store)],+ _user: Annotated[User, Depends(require_tenant_admin)],+) -> BudgetResponse:+ """Add a budget to the bound tenant. `owner`/`admin` only.++ 404 when `agent_id` names no agent in this workspace; 409 when the same+ agent (or the whole workspace), metric and model already has one — edit+ that one instead.+ """+ _require_bound_tenant(tenant_id)+ if body.agent_id is not None:+ agent = await agent_store.get(session, body.agent_id)+ if agent is None or agent.tenant_id != tenant_id:+ raise HTTPException(status_code=404, detail="Agent not found")+ try:+ budget = await budget_store.create(+ session,+ tenant_id=tenant_id,+ agent_id=body.agent_id,+ metric=body.metric,+ model=body.model,+ amount_limit=body.amount_limit,+ period_hours=body.period_hours,+ )+ except IntegrityError as exc:+ raise HTTPException(+ status_code=409,+ detail="A budget for this agent, metric and model already exists",+ ) from exc+ await session.commit()+ return await _budget_standing(session, budget_store, tenant_id, budget.id)++[email protected]("/tenants/{tenant_id}/budgets/{budget_id}")+async def update_budget(+ tenant_id: str,+ budget_id: str,+ body: BudgetUpdateRequest,+ session: Annotated[AsyncSession, Depends(get_session)],+ budget_store: Annotated[BudgetStore, Depends(get_budget_store)],+ _user: Annotated[User, Depends(require_tenant_admin)],+) -> BudgetResponse:+ """Change a budget's limit and period. `owner`/`admin` only. What it+ covers is fixed; to cover something else, add another budget."""+ _require_bound_tenant(tenant_id)+ try:+ await budget_store.update(+ session,+ tenant_id=tenant_id,+ budget_id=budget_id,+ amount_limit=body.amount_limit,+ period_hours=body.period_hours,+ )+ except BudgetNotFound as exc:+ raise HTTPException(status_code=404, detail="Budget not found") from exc+ await session.commit()+ return await _budget_standing(session, budget_store, tenant_id, budget_id)++[email protected]("/tenants/{tenant_id}/budgets/{budget_id}", status_code=204)+async def delete_budget(+ tenant_id: str,+ budget_id: str,+ session: Annotated[AsyncSession, Depends(get_session)],+ budget_store: Annotated[BudgetStore, Depends(get_budget_store)],+ _user: Annotated[User, Depends(require_tenant_admin)],+) -> Response:+ """Remove a budget. `owner`/`admin` only."""+ _require_bound_tenant(tenant_id)+ try:+ await budget_store.delete(session, tenant_id=tenant_id, budget_id=budget_id)+ except BudgetNotFound as exc:+ raise HTTPException(status_code=404, detail="Budget not found") from exc+ await session.commit()+ return Response(status_code=204)++@router.get("/tenants/{tenant_id}/invitations")async def list_invitations(tenant_id: str,diff --git a/core/switch_core/main.py b/core/switch_core/main.pyindex 6ae94c806..401f6749e 100644--- a/core/switch_core/main.py+++ b/core/switch_core/main.py@@ -100,6 +100,7 @@ from switch_core.db.stores.agent_session_store import AgentSessionStorefrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.api_key_store import ApiKeyStorefrom switch_core.db.stores.bridge_message_map_store import BridgeMessageMapStore+from switch_core.db.stores.budget_store import BudgetStorefrom switch_core.db.stores.client_store import ClientStorefrom switch_core.db.stores.collaboration_bridge_store import CollaborationBridgeStorefrom switch_core.db.stores.document_store import DocumentStore@@ -390,6 +391,7 @@ async def run(config: SwitchConfig) -> None:room_role_store = RoomRoleStore()message_store = MessageStore()usage_store = UsageStore()+ budget_store = BudgetStore()media_store = MediaStore()template_store = TemplateStore()@@ -645,6 +647,7 @@ async def run(config: SwitchConfig) -> None:invitation_store=invitation_store,template_store=template_store,usage_store=usage_store,+ budget_store=budget_store,resource_service=resource_service,protocol=protocol,install_service=install_service,diff --git a/core/switch_core/migrations/versions/e3b7c9d2a415_usage_budgets.py b/core/switch_core/migrations/versions/e3b7c9d2a415_usage_budgets.pynew file mode 100644index 000000000..2f56507eb--- /dev/null+++ b/core/switch_core/migrations/versions/e3b7c9d2a415_usage_budgets.py@@ -0,0 +1,112 @@+"""usage budgets: a ceiling on a metric over a repeating period++Revision ID: e3b7c9d2a415+Revises: c7e4a91d3b20++A budget caps one metric of ``tenant_usage`` for a whole tenant or for one+agent, optionally for one model, over a period of whole hours. An agent that+has reached a budget covering it is stopped until the period turns over. A+tenant with no budgets is unlimited, so nothing changes for existing tenants+when this runs.++Two partial unique indexes stand in for one unique constraint: ``agent_id`` is+null for a tenant-wide budget, and nulls never collide in a plain constraint.++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 = "e3b7c9d2a415"+down_revision: str | Sequence[str] | None = "c7e4a91d3b20"+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 "usage_budgets"\n'+ f" FOR ALL\n"+ f" USING ({_PREDICATE})\n"+ f" WITH CHECK ({_PREDICATE})"+)++_METRICS = (+ "messages",+ "turns",+ "input_tokens",+ "output_tokens",+ "cache_read_tokens",+ "cache_write_tokens",+)+++def upgrade() -> None:+ op.create_table(+ "usage_budgets",+ sa.Column("tenant_id", sa.Text(), nullable=False),+ sa.Column("id", sa.Text(), nullable=False),+ sa.Column("agent_id", sa.Text(), nullable=True),+ sa.Column("metric", sa.Text(), nullable=False),+ sa.Column("model", sa.Text(), nullable=False),+ sa.Column("amount_limit", sa.BigInteger(), nullable=False),+ sa.Column("period_hours", sa.Integer(), nullable=False),+ sa.Column(+ "created_at",+ sa.DateTime(timezone=True),+ server_default=sa.text("now()"),+ nullable=False,+ ),+ sa.ForeignKeyConstraint(+ ["tenant_id"], ["tenants.id"], name="fk_usage_budgets_tenant"+ ),+ sa.ForeignKeyConstraint(+ ["tenant_id", "agent_id"],+ ["agents.tenant_id", "agents.id"],+ name="fk_usage_budgets_agent",+ ondelete="CASCADE",+ ),+ sa.CheckConstraint(+ "metric IN ({})".format(", ".join(f"'{m}'" for m in _METRICS)),+ name="ck_usage_budgets_metric",+ ),+ sa.CheckConstraint(+ "amount_limit > 0 AND amount_limit <= 9007199254740991",+ name="ck_usage_budgets_amount_limit",+ ),+ sa.CheckConstraint(+ "period_hours > 0 AND period_hours <= 8784",+ name="ck_usage_budgets_period_hours",+ ),+ sa.PrimaryKeyConstraint("id"),+ )+ op.create_index(+ "uq_usage_budgets_tenant_wide",+ "usage_budgets",+ ["tenant_id", "metric", "model"],+ unique=True,+ postgresql_where=sa.text("agent_id IS NULL"),+ )+ op.create_index(+ "uq_usage_budgets_agent",+ "usage_budgets",+ ["tenant_id", "agent_id", "metric", "model"],+ unique=True,+ postgresql_where=sa.text("agent_id IS NOT NULL"),+ )+ op.execute('ALTER TABLE "usage_budgets" ENABLE ROW LEVEL SECURITY')+ op.execute(_CREATE_POLICY)+++def downgrade() -> None:+ op.execute(f'DROP POLICY IF EXISTS {POLICY_NAME} ON "usage_budgets"')+ op.drop_index("uq_usage_budgets_agent", table_name="usage_budgets")+ op.drop_index("uq_usage_budgets_tenant_wide", table_name="usage_budgets")+ op.drop_table("usage_budgets")diff --git a/core/tests/switch_core/bridges/agent/protocol/test_delegate_addressing.py b/core/tests/switch_core/bridges/agent/protocol/test_delegate_addressing.pyindex a85147746..422b4c44b 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_delegate_addressing.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_delegate_addressing.py@@ -6,10 +6,22 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.protocol.connections import ConnectionRegistryfrom switch_core.bridges.agent.protocol.service import ProtocolServicefrom switch_core.bridges.agent.protocol.types import AgentStatus-from switch_core.db.models import Agent, ApiKey, Client, Room, User+from switch_core.budgets import BudgetExceeded, BudgetGuard+from switch_core.db.models import (+ Agent,+ ApiKey,+ Client,+ Room,+ UsageBudget,+ UsageMetric,+ User,+ require_tenant_id,+)from switch_core.db.stores.agent_store import AgentStore+from switch_core.db.stores.budget_store import BudgetStorefrom switch_core.db.stores.room_store import RoomStorefrom switch_core.db.stores.task_store import TaskStore+from switch_core.db.stores.usage_store import UsageStoredef _service(session_factory: async_sessionmaker[AsyncSession]) -> ProtocolService:@@ -21,6 +33,7 @@ def _service(session_factory: async_sessionmaker[AsyncSession]) -> ProtocolServisvc.agent_store = AgentStore() # type: ignore[attr-defined]svc.room_store = RoomStore() # type: ignore[attr-defined]svc.task_store = TaskStore() # type: ignore[attr-defined]+ svc.budget_guard = BudgetGuard(BudgetStore()) # type: ignore[attr-defined]# No live matrix client → delegate_task skips the custom-event send.svc.client_lifecycle = _NoClients() # type: ignore[attr-defined]@@ -218,3 +231,57 @@ class TestDelegateAddressingGate:result = await svc.delegate_task(req_id, room_id, perf_id, "do it", "details")assert result.task_id+++async def _spend_budget(session: AsyncSession, agent: Agent) -> None:+ session.add(+ UsageBudget(+ agent_id=agent.id,+ metric="turns",+ model="",+ amount_limit=1,+ period_hours=24,+ )+ )+ await UsageStore().record(+ session,+ tenant_id=require_tenant_id(),+ metric=UsageMetric.TURNS,+ client_id=agent.client_id,+ model="",+ amount=1,+ )+++class TestDelegateBudgetGate:+ @pytest.mark.parametrize("over_budget", ["requester", "performer"])+ async def test_an_agent_over_its_budget_takes_no_part_in_a_delegation(+ self, session_factory: async_sessionmaker[AsyncSession], over_budget: str+ ) -> None:+ svc = _service(session_factory)+ async with session_factory() as session:+ owner = await _make_user(session, "owner")+ requester = await _make_agent(session, "req", owner_id=owner.id)+ performer = await _make_agent(+ session,+ "perf",+ owner_id=owner.id,+ addressing_policy={+ "rules": [{"users": [], "agents": [], "owner_agents": True}]+ },+ )+ room = await _make_room(+ session, svc.room_store, [requester.id, performer.id]+ )+ await _spend_budget(+ session, requester if over_budget == "requester" else performer+ )+ await session.commit()+ req_id, perf_id, room_id = requester.id, performer.id, room.id++ with pytest.raises(BudgetExceeded, match="has reached its budget of 1 turns"):+ await svc.delegate_task(req_id, room_id, perf_id, "do it", "details")++ async with session_factory() as session:+ tasks = await svc.task_store.get_by_room(session, room_id)+ assert tasks == []diff --git a/core/tests/switch_core/bridges/agent/protocol/test_pool_checkouts.py b/core/tests/switch_core/bridges/agent/protocol/test_pool_checkouts.pyindex fc5aed1f1..891d8e0cb 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_pool_checkouts.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_pool_checkouts.py@@ -19,10 +19,21 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.protocol.connections import ConnectionRegistryfrom switch_core.bridges.agent.protocol.service import ProtocolServicefrom switch_core.bridges.agent.protocol.types import RoomDescriptor-from switch_core.db.models import Agent, ApiKey, Client, Room, User+from switch_core.budgets import BudgetExceeded, BudgetGuard+from switch_core.db.models import (+ Agent,+ ApiKey,+ Client,+ Room,+ UsageBudget,+ UsageMetric,+ User,+)from switch_core.db.stores.agent_session_store import AgentSessionStorefrom switch_core.db.stores.agent_store import AgentStore+from switch_core.db.stores.budget_store import BudgetStorefrom switch_core.db.stores.room_store import RoomStore+from switch_core.db.stores.usage_store import UsageStoreclass _CountingSessionFactory:@@ -62,6 +73,7 @@ def _service(counting: _CountingSessionFactory) -> ProtocolService:svc.session_factory = counting # type: ignore[attr-defined]svc.agent_store = AgentStore() # type: ignore[attr-defined]svc.room_store = RoomStore() # type: ignore[attr-defined]+ svc.budget_guard = BudgetGuard(BudgetStore()) # type: ignore[attr-defined]svc.collab_lifecycle = _NoBridges() # type: ignore[attr-defined]svc.connections = ConnectionRegistry()return svc@@ -328,6 +340,39 @@ class TestSendMessage:with pytest.raises(PermissionError):await svc.send_message(outsider_id, room_id, "hello")+ async def test_an_agent_over_its_budget_cannot_post_and_it_costs_one_checkout(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ room_id, member_id, _ = await _seed(session_factory)+ async with session_factory() as session:+ agent = await AgentStore().get(session, member_id)+ assert agent is not None+ session.add(+ UsageBudget(+ agent_id=member_id,+ metric="messages",+ model="",+ amount_limit=2,+ period_hours=24,+ )+ )+ await UsageStore().record(+ session,+ tenant_id=agent.tenant_id,+ metric=UsageMetric.MESSAGES,+ client_id=agent.client_id,+ model="",+ amount=2,+ )+ await session.commit()+ counting = _CountingSessionFactory(session_factory)+ svc = _service(counting)++ with pytest.raises(BudgetExceeded, match="member has reached its budget"):+ await svc.send_message(member_id, room_id, "hello")++ assert counting.opened == 1+class TestAgentStatuses:async def test_a_request_handler_can_reuse_its_own_session(diff --git a/core/tests/switch_core/bridges/agent/protocol/test_send_media.py b/core/tests/switch_core/bridges/agent/protocol/test_send_media.pyindex 06ed2bc3c..1eff08346 100644--- a/core/tests/switch_core/bridges/agent/protocol/test_send_media.py+++ b/core/tests/switch_core/bridges/agent/protocol/test_send_media.py@@ -60,7 +60,7 @@ def _build_service(client: _FakeClient, *, max_bytes: int = 100) -> ProtocolServ# Presence unions the heartbeat rows with the live connections# (CHOO-1857); an empty registry means "rows only".svc.connections = ConnectionRegistry()- svc.require_room_member = _require # type: ignore[assignment]+ svc.require_room_poster = _require # type: ignore[assignment]svc.client_lifecycle = SimpleNamespace( # type: ignore[assignment]get_by_agent_id=lambda agent_id: client)diff --git a/core/tests/switch_core/clients/test_addressing_enforcement.py b/core/tests/switch_core/clients/test_addressing_enforcement.pyindex 1bc1a6900..0fd68f3aa 100644--- a/core/tests/switch_core/clients/test_addressing_enforcement.py+++ b/core/tests/switch_core/clients/test_addressing_enforcement.py@@ -1,10 +1,13 @@from __future__ import annotationsfrom contextlib import asynccontextmanager+from datetime import UTC, datetimefrom types import SimpleNamespace+from switch_core.budgets import BudgetGuardfrom switch_core.clients.admin_messages import PLATFORM_MARKER as _PLATFORM_MARKERfrom switch_core.clients.agent_client import AUTO_REPLY_FLAG, AgentClient+from switch_core.db.stores.budget_store import BudgetStandingfrom switch_core.delivery.addressing import (ADDRESSING_DENIED_MESSAGE as _ADDRESSING_DENIED_MESSAGE,)@@ -508,7 +511,34 @@ class TestOwnerAgentsAddressing:assert (await _decide(client)).refusal == _ADDRESSING_DENIED_MESSAGE-def _gate_client(*, allowed: bool, refusal: str = _ADDRESSING_DENIED_MESSAGE): # type: ignore[no-untyped-def]+def _standing(*, spent: int) -> BudgetStanding:+ return BudgetStanding(+ id="budget-1",+ agent_id="agent-1",+ agent_name="fixer",+ metric="turns",+ model="",+ amount_limit=10,+ period_hours=24,+ spent=spent,+ resets_at=datetime(2026, 1, 2, tzinfo=UTC),+ )+++class _FakeBudgetStore:+ def __init__(self, standings: list[BudgetStanding]) -> None:+ self._standings = standings++ async def standings(self, _session, *, tenant_id, agent_id): # type: ignore[no-untyped-def]+ return self._standings+++def _gate_client( # type: ignore[no-untyped-def]+ *,+ allowed: bool,+ refusal: str = _ADDRESSING_DENIED_MESSAGE,+ budgets: list[BudgetStanding] | None = None,+):"""Fake client for _gate_addressed and the auto-reply it hands back."""sent: list[dict] = []@@ -524,7 +554,9 @@ def _gate_client(*, allowed: bool, refusal: str = _ADDRESSING_DENIED_MESSAGE):return "human"client = SimpleNamespace(- agent=SimpleNamespace(name="fixer"),+ agent=SimpleNamespace(id="agent-1", name="fixer"),+ tenant_id="tenant-1",+ _budget_guard=BudgetGuard(_FakeBudgetStore(budgets or [])), # type: ignore[arg-type]_addressing_allowed=_addressing_allowed,send_message=_send_message,_sender_handle=_sender_handle,@@ -599,6 +631,32 @@ class TestGateAddressed:assert outcome.refusal == _ADDRESSING_DENIED_MESSAGEassert client.sent == []+ async def test_an_agent_within_its_budget_stays_addressed(self) -> None:+ client = _gate_client(allowed=True, budgets=[_standing(spent=9)])+ outcome = await _gate(client, _event())+ assert outcome.addressed is True+ assert client.sent == []++ async def test_an_agent_over_budget_is_demoted_and_says_so(self) -> None:+ client = _gate_client(allowed=True, budgets=[_standing(spent=10)])+ outcome = await _gate(client, _event())+ assert outcome.addressed is False+ reply = client.sent[0]+ assert "Agent fixer has reached its budget of 10 turns per 24h" in reply["body"]+ assert "2026-01-02 00:00 UTC" in reply["body"]+ assert reply["extra_content"] == {AUTO_REPLY_FLAG: True}++ async def test_an_over_budget_agent_does_not_answer_an_auto_reply(self) -> None:+ client = _gate_client(allowed=True, budgets=[_standing(spent=10)])+ outcome = await _gate(client, _event(auto_reply=True))+ assert outcome.addressed is False+ assert client.sent == []++ async def test_a_denied_sender_hears_the_policy_not_the_budget(self) -> None:+ client = _gate_client(allowed=False, budgets=[_standing(spent=10)])+ await _gate(client, _event())+ assert _ADDRESSING_DENIED_MESSAGE in client.sent[0]["body"]+def _command(args: str = "", user_id: str = "@u:switch.local", command: str = "reset"diff --git a/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py b/core/tests/switch_core/clients/test_agent_client_pool_checkouts.pyindex be99ab135..f300d3e66 100644--- a/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py+++ b/core/tests/switch_core/clients/test_agent_client_pool_checkouts.py@@ -20,11 +20,13 @@ from typing import Anyfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmakerfrom switch_core.bridges.agent.protocol.connections import ConnectionRegistry+from switch_core.budgets import BudgetGuardfrom switch_core.clients.agent_client import AgentClientfrom switch_core.clients.room_meta import RoomMetafrom switch_core.db.models import Agent, ApiKey, Client, Room, Userfrom switch_core.db.stores.agent_session_store import AgentSessionStorefrom switch_core.db.stores.agent_store import AgentStore+from switch_core.db.stores.budget_store import BudgetStorefrom switch_core.db.stores.client_store import ClientStorefrom switch_core.db.stores.external_user_store import ExternalUserStorefrom switch_core.db.stores.room_role_store import RoomRoleStore@@ -120,6 +122,7 @@ def _client(client.client_store = ClientStore()client.matrix_user_id = f"@{agent.name}:test"client.client_id = agent.client_id+ client.tenant_id = agent.tenant_idclient._agent = agentclient._agent_store = AgentStore()client._room_store = RoomStore()@@ -135,6 +138,7 @@ def _client(external_user_store=client._external_user_store,live_connection_ids=client._connections.live_connection_ids,)+ client._budget_guard = BudgetGuard(BudgetStore())client._frontend_base_url = Noneclient._room_meta = {MATRIX_ROOM_ID: RoomMeta(diff --git a/core/tests/switch_core/db/stores/test_budget_store.py b/core/tests/switch_core/db/stores/test_budget_store.pynew file mode 100644index 000000000..d29460674--- /dev/null+++ b/core/tests/switch_core/db/stores/test_budget_store.py@@ -0,0 +1,333 @@+"""Budgets and what has been spent against them, against a real database.++The period arithmetic and the spend sum are SQL, so none of this is mocked.+"""++from __future__ import annotations++from datetime import UTC, datetime, timedelta++import pytest+from sqlalchemy.exc import IntegrityError+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker++from switch_core.budgets import BudgetExceeded, BudgetGuard+from switch_core.db.models import (+ MAX_BUDGET_AMOUNT,+ MAX_BUDGET_PERIOD_HOURS,+ TENANT_ZERO_ID,+ Agent,+ ApiKey,+ Client,+ TenantUsage,+ UsageMetric,+ User,+)+from switch_core.db.stores.budget_store import BudgetNotFound, BudgetStore+++async def _agent(session: AsyncSession, name: str) -> Agent:+ owner = User(+ id=f"owner-{name}", name=name, email=f"{name}@example.test", role="user"+ )+ session.add(owner)+ await session.flush()+ client = Client(matrix_user_id=f"@{name}:test", display_name=name, type="agent")+ key = ApiKey(+ user_id=owner.id,+ key_hash=f"hash-{name}",+ encrypted_key="",+ label="unused fixture",+ type="agent",+ )+ session.add_all([client, key])+ await session.flush()+ agent = Agent(+ name=name,+ description="test agent",+ agent_type="session_addressable",+ connector_type="codex",+ integration_profile={},+ client_id=client.id,+ api_key_id=key.id,+ )+ session.add(agent)+ await session.flush()+ return agent+++def _hour(offset: int) -> datetime:+ now = datetime.now(UTC).replace(minute=0, second=0, microsecond=0)+ return now + timedelta(hours=offset)+++def _spent(client_id: str, amount: int, *, metric="turns", model="", hour=0):+ return TenantUsage(+ metric=metric,+ bucket_start=_hour(hour),+ client_id=client_id,+ model=model,+ amount=amount,+ )+++async def _budget(+ session: AsyncSession,+ *,+ agent_id: str | None,+ metric: UsageMetric = UsageMetric.TURNS,+ model: str = "",+ amount_limit: int = 10,+ period_hours: int = 1,+):+ return await BudgetStore().create(+ session,+ tenant_id=TENANT_ZERO_ID,+ agent_id=agent_id,+ metric=metric,+ model=model,+ amount_limit=amount_limit,+ period_hours=period_hours,+ )+++async def _standings(session: AsyncSession, agent_id: str | None):+ return await BudgetStore().standings(+ session, tenant_id=TENANT_ZERO_ID, agent_id=agent_id+ )+++class TestSpend:+ async def test_an_agent_budget_counts_only_that_agent_this_period(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ mine = await _agent(session, "mine")+ other = await _agent(session, "other")+ await _budget(session, agent_id=mine.id)+ session.add_all(+ [+ _spent(mine.client_id, 3),+ _spent(mine.client_id, 100, hour=-1),+ _spent(other.client_id, 50),+ ]+ )+ await session.commit()++ async with session_factory() as session:+ [standing] = await _standings(session, None)++ assert standing.agent_name == "mine"+ assert standing.spent == 3+ assert standing.resets_at == _hour(1)+ assert not standing.exhausted++ async def test_a_daily_budget_turns_over_at_midnight_utc(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ await _budget(session, agent_id=None, period_hours=24)+ await session.commit()++ async with session_factory() as session:+ [standing] = await _standings(session, None)++ midnight = datetime.now(UTC).replace(hour=0, minute=0, second=0, microsecond=0)+ assert standing.resets_at == midnight + timedelta(days=1)++ async def test_a_tenant_wide_budget_counts_every_agent_and_no_one_else(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ one = await _agent(session, "one")+ two = await _agent(session, "two")+ await _budget(session, agent_id=None, metric=UsageMetric.MESSAGES)+ session.add_all(+ [+ _spent("a-person", 40, metric="messages"),+ _spent("a-bridge", 40, metric="messages"),+ _spent(one.client_id, 4, metric="messages"),+ _spent(two.client_id, 6, metric="messages"),+ ]+ )+ await session.commit()++ async with session_factory() as session:+ [standing] = await _standings(session, None)++ assert standing.agent_id is None+ assert standing.spent == 10+ assert standing.exhausted++ async def test_a_model_budget_counts_only_that_model(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent = await _agent(session, "modelled")+ await _budget(+ session,+ agent_id=agent.id,+ metric=UsageMetric.OUTPUT_TOKENS,+ model="big",+ amount_limit=1000,+ )+ session.add_all(+ [+ _spent(agent.client_id, 300, metric="output_tokens", model="big"),+ _spent(agent.client_id, 900, metric="output_tokens", model="small"),+ ]+ )+ await session.commit()++ async with session_factory() as session:+ [standing] = await _standings(session, None)++ assert standing.spent == 300++ async def test_an_agent_is_covered_by_its_own_and_tenant_wide_budgets(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ mine = await _agent(session, "covered")+ other = await _agent(session, "elsewhere")+ await _budget(session, agent_id=None)+ await _budget(session, agent_id=mine.id)+ await _budget(session, agent_id=other.id)+ await session.commit()++ async with session_factory() as session:+ covering = await _standings(session, mine.id)++ assert [s.agent_id for s in covering] == [None, mine.id]+++class TestChanges:+ async def test_a_second_budget_on_the_same_thing_is_refused(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ await _budget(session, agent_id=None)+ with pytest.raises(IntegrityError, match="uq_usage_budgets_tenant_wide"):+ await _budget(session, agent_id=None, amount_limit=99)++ @pytest.mark.parametrize(+ ("amount_limit", "period_hours", "constraint"),+ [+ (MAX_BUDGET_AMOUNT + 1, 24, "ck_usage_budgets_amount_limit"),+ (10, MAX_BUDGET_PERIOD_HOURS + 1, "ck_usage_budgets_period_hours"),+ ],+ )+ async def test_a_budget_past_the_bounds_is_refused(+ self,+ session_factory: async_sessionmaker[AsyncSession],+ amount_limit: int,+ period_hours: int,+ constraint: str,+ ) -> None:+ async with session_factory() as session:+ with pytest.raises(IntegrityError, match=constraint):+ await _budget(+ session,+ agent_id=None,+ amount_limit=amount_limit,+ period_hours=period_hours,+ )++ async def test_the_longest_budget_reads_its_standing(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent = await _agent(session, "yearly")+ session.add(_spent(agent.client_id, 4))+ await _budget(+ session,+ agent_id=agent.id,+ amount_limit=MAX_BUDGET_AMOUNT,+ period_hours=MAX_BUDGET_PERIOD_HOURS,+ )+ [standing] = await _standings(session, agent.id)++ assert standing.spent == 4+ assert standing.resets_at > datetime.now(UTC)++ async def test_update_and_delete_name_a_budget_that_exists(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ store = BudgetStore()+ async with session_factory() as session:+ budget = await _budget(session, agent_id=None)+ await store.update(+ session,+ tenant_id=TENANT_ZERO_ID,+ budget_id=budget.id,+ amount_limit=5,+ period_hours=48,+ )+ [standing] = await _standings(session, None)+ assert (standing.amount_limit, standing.period_hours) == (5, 48)++ await store.delete(session, tenant_id=TENANT_ZERO_ID, budget_id=budget.id)+ assert await _standings(session, None) == []+ with pytest.raises(BudgetNotFound):+ await store.delete(+ session, tenant_id=TENANT_ZERO_ID, budget_id=budget.id+ )++ async def test_deleting_an_agent_deletes_its_budgets(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent = await _agent(session, "deleted")+ await _budget(session, agent_id=agent.id)+ await session.commit()+ await session.delete(agent)+ await session.commit()++ async with session_factory() as session:+ assert await _standings(session, None) == []+++class TestGuard:+ async def test_an_agent_within_its_budgets_passes(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent = await _agent(session, "within")+ await _budget(session, agent_id=agent.id)+ session.add(_spent(agent.client_id, 9))+ await session.flush()++ await BudgetGuard(BudgetStore()).require_within(+ session, tenant_id=TENANT_ZERO_ID, agent_id=agent.id+ )++ async def test_the_budget_that_stops_the_agent_longest_is_reported(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ async with session_factory() as session:+ agent = await _agent(session, "stopped")+ await _budget(session, agent_id=agent.id, period_hours=1)+ await _budget(+ session,+ agent_id=None,+ metric=UsageMetric.MESSAGES,+ amount_limit=2,+ period_hours=24,+ )+ session.add_all(+ [+ _spent(agent.client_id, 10),+ _spent(agent.client_id, 2, metric="messages"),+ ]+ )+ await session.flush()++ with pytest.raises(BudgetExceeded) as stopped:+ await BudgetGuard(BudgetStore()).require_within(+ session, tenant_id=TENANT_ZERO_ID, agent_id=agent.id+ )++ assert stopped.value.standing.metric == "messages"+ assert str(stopped.value).startswith(+ "This workspace has reached its budget of 2 messages per 24h."+ )diff --git a/core/tests/switch_core/gateway/test_tenant_api_routes.py b/core/tests/switch_core/gateway/test_tenant_api_routes.pyindex 6997b7cc1..2d4c048b0 100644--- a/core/tests/switch_core/gateway/test_tenant_api_routes.py+++ b/core/tests/switch_core/gateway/test_tenant_api_routes.py@@ -22,6 +22,7 @@ from datetime import UTC, datetime, timedeltafrom types import SimpleNamespaceimport httpx+import pytestfrom fastapi import FastAPIfrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker@@ -39,6 +40,7 @@ from switch_core.db.models import (from switch_core.db.session_scope import tenant_sessionfrom switch_core.db.stores.agent_store import AgentStorefrom switch_core.db.stores.api_key_store import ApiKeyStore+from switch_core.db.stores.budget_store import BudgetStorefrom switch_core.db.stores.invitation_store import InvitationStorefrom switch_core.db.stores.usage_store import UsageStorefrom switch_core.db.stores.user_store import UserStore@@ -92,6 +94,7 @@ def _app(app.dependency_overrides[gw_deps.get_api_key_store] = lambda: ApiKeyStore()app.dependency_overrides[gw_deps.get_invitation_store] = lambda: InvitationStore()app.dependency_overrides[gw_deps.get_usage_store] = lambda: UsageStore()+ app.dependency_overrides[gw_deps.get_budget_store] = lambda: BudgetStore()app.dependency_overrides[gw_deps.get_protocol] = lambda: _fake_protocol()app.dependency_overrides[gw_deps.get_client_lifecycle] = lambda: (client_lifecycle or _FakeClientLifecycle(session_factory)@@ -1242,3 +1245,233 @@ class TestUsageRoute:)assert response.status_code == 400+++class TestBudgetRoutes:+ async def _admin(+ self, session_factory: async_sessionmaker[AsyncSession], name: str+ ) -> tuple[str, str]:+ await _make_tenant(session_factory, TENANT_A)+ user_id = await _make_member(+ session_factory, name=name, tenant_id=TENANT_A, role="admin"+ )+ return user_id, _token(user_id, f"{name}@example.invalid", TENANT_A)++ async def test_an_admin_sets_a_budget_and_sees_its_spend(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ user_id, token = await self._admin(session_factory, "budget-admin")+ agent_id, agent_name, _ = await _make_agent_with_key(+ session_factory, tenant_id=TENANT_A, owner_id=user_id+ )+ async with session_factory() as session:+ agent = await AgentStore().get(session, agent_id)+ assert agent is not None+ await UsageStore().record(+ session,+ tenant_id=TENANT_A,+ metric=UsageMetric.TURNS,+ client_id=agent.client_id,+ model="",+ amount=3,+ )+ await session.commit()++ async with _client(_app(session_factory), token) as client:+ created = await client.post(+ f"/tenants/{TENANT_A}/budgets",+ json={+ "agent_id": agent_id,+ "metric": "turns",+ "model": "",+ "amount_limit": 3,+ "period_hours": 24,+ },+ )+ listed = await client.get(f"/tenants/{TENANT_A}/budgets")++ assert created.status_code == 201+ body = created.json()+ assert body["agent_name"] == agent_name+ assert (body["spent"], body["exhausted"]) == (3, True)+ assert listed.json() == [body]++ async def test_a_second_budget_on_the_same_thing_is_a_conflict(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ _, token = await self._admin(session_factory, "budget-twice")+ budget = {+ "agent_id": None,+ "metric": "messages",+ "model": "",+ "amount_limit": 100,+ "period_hours": 24,+ }++ async with _client(_app(session_factory), token) as client:+ first = await client.post(f"/tenants/{TENANT_A}/budgets", json=budget)+ second = await client.post(f"/tenants/{TENANT_A}/budgets", json=budget)++ assert first.status_code == 201+ assert second.status_code == 409++ @pytest.mark.parametrize("metric", ["messages", "turns"])+ async def test_a_budget_on_a_metric_counted_without_a_model_cannot_name_one(+ self, session_factory: async_sessionmaker[AsyncSession], metric: str+ ) -> None:+ _, token = await self._admin(session_factory, f"budget-model-{metric}")++ async with _client(_app(session_factory), token) as client:+ response = await client.post(+ f"/tenants/{TENANT_A}/budgets",+ json={+ "agent_id": None,+ "metric": metric,+ "model": "some-model",+ "amount_limit": 100,+ "period_hours": 24,+ },+ )++ assert response.status_code == 422+ assert "not counted per model" in response.text++ @pytest.mark.parametrize(+ ("amount_limit", "period_hours"),+ [(2**53, 24), (100, 8785), (0, 24), (100, 0)],+ )+ async def test_a_budget_past_the_bounds_is_refused(+ self,+ session_factory: async_sessionmaker[AsyncSession],+ amount_limit: int,+ period_hours: int,+ ) -> None:+ _, token = await self._admin(session_factory, "budget-bounds")+ limits = {"amount_limit": amount_limit, "period_hours": period_hours}++ async with _client(_app(session_factory), token) as client:+ created = await client.post(+ f"/tenants/{TENANT_A}/budgets",+ json={"agent_id": None, "metric": "turns", "model": "", **limits},+ )+ within = await client.post(+ f"/tenants/{TENANT_A}/budgets",+ json={+ "agent_id": None,+ "metric": "turns",+ "model": "",+ "amount_limit": 100,+ "period_hours": 24,+ },+ )+ updated = await client.put(+ f"/tenants/{TENANT_A}/budgets/{within.json()['id']}", json=limits+ )++ assert created.status_code == 422+ assert within.status_code == 201+ assert updated.status_code == 422++ async def test_a_budget_for_another_workspaces_agent_is_not_found(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ _, token = await self._admin(session_factory, "budget-foreign")+ await _make_tenant(session_factory, TENANT_B)+ their_owner = await _make_member(+ session_factory, name="budget-theirs", tenant_id=TENANT_B, role="owner"+ )+ their_agent, _, _ = await _make_agent_with_key(+ session_factory, tenant_id=TENANT_B, owner_id=their_owner+ )++ async with _client(_app(session_factory), token) as client:+ response = await client.post(+ f"/tenants/{TENANT_A}/budgets",+ json={+ "agent_id": their_agent,+ "metric": "turns",+ "model": "",+ "amount_limit": 1,+ "period_hours": 24,+ },+ )++ assert response.status_code == 404++ async def test_a_limit_that_is_not_positive_is_refused(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ _, token = await self._admin(session_factory, "budget-zero")++ async with _client(_app(session_factory), token) as client:+ response = await client.post(+ f"/tenants/{TENANT_A}/budgets",+ json={+ "agent_id": None,+ "metric": "turns",+ "model": "",+ "amount_limit": 0,+ "period_hours": 24,+ },+ )++ assert response.status_code == 422++ async def test_an_admin_changes_and_removes_a_budget(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ _, token = await self._admin(session_factory, "budget-edit")++ async with _client(_app(session_factory), token) as client:+ created = await client.post(+ f"/tenants/{TENANT_A}/budgets",+ json={+ "agent_id": None,+ "metric": "output_tokens",+ "model": "some-model",+ "amount_limit": 1000,+ "period_hours": 24,+ },+ )+ budget_id = created.json()["id"]+ updated = await client.put(+ f"/tenants/{TENANT_A}/budgets/{budget_id}",+ json={"amount_limit": 5000, "period_hours": 168},+ )+ deleted = await client.delete(f"/tenants/{TENANT_A}/budgets/{budget_id}")+ again = await client.delete(f"/tenants/{TENANT_A}/budgets/{budget_id}")+ listed = await client.get(f"/tenants/{TENANT_A}/budgets")++ assert updated.status_code == 200+ assert (updated.json()["amount_limit"], updated.json()["period_hours"]) == (+ 5000,+ 168,+ )+ assert deleted.status_code == 204+ assert again.status_code == 404+ assert listed.json() == []++ async def test_a_plain_member_cannot_see_budgets(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ await _make_tenant(session_factory, TENANT_A)+ user_id = await _make_member(+ session_factory, name="budget-member", tenant_id=TENANT_A, role="member"+ )+ token = _token(user_id, "[email protected]", TENANT_A)++ async with _client(_app(session_factory), token) as client:+ response = await client.get(f"/tenants/{TENANT_A}/budgets")++ assert response.status_code == 403++ async def test_an_admin_of_a_cannot_touch_bs_budgets(+ self, session_factory: async_sessionmaker[AsyncSession]+ ) -> None:+ _, token = await self._admin(session_factory, "budget-snoop")+ await _make_tenant(session_factory, TENANT_B)++ async with _client(_app(session_factory), token) as client:+ response = await client.get(f"/tenants/{TENANT_B}/budgets")++ assert response.status_code == 403