feat(webapp,dashboard-agent-db): server-side agent message quota

Enforce the Free plan's agent-message allowance on the server, not just as a
client hint. A per-(organizationId, period) counter lives in its own table,
not joined to chats, so deleting a chat can no longer free quota inside the
period. The create path and the .in append path each count one user message
and refuse over the cap with a typed 403 the client renders as the upgrade
block; wakes (action turns) never count. Fails open: an absent limit
(self-hosted, or before the cloud side ships) or a counter read that throws
means no cap. TRI-12863.

Author: kathiekiwi

.server-changes/agent-message-quota.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+The Free plan now includes a monthly allowance of agent messages. When you reach it, the chat shows an upgrade prompt in place of the composer; your existing chats stay readable.

apps/webapp/app/components/dashboard-agent/DashboardAgentChat.tsx

@@ -17,6 +17,7 @@ import { DashboardAgentContextBanner } from "./DashboardAgentContextBanner";
 import { DashboardAgentHero } from "./DashboardAgentHero";
 import { DashboardAgentMessages, type TurnActivity } from "./DashboardAgentMessages";
 import { MESSAGE_TOO_LARGE_ERROR } from "./message-limits";
+import { FREE_PLAN_MESSAGE_LIMIT } from "./message-quota";
 import { createTranscriptOrder, orderTranscript } from "./message-order";
 import { navigateDestination } from "./navigate-target";
 import { pendingNavigateIntents, pendingWatchIntents } from "./pending-intents";
@@ -102,6 +103,9 @@ export function DashboardAgentChat({
   onActivityChange?: (chatId: string, activity: TurnActivity | null) => void;
 }) {
   const [input, setInput] = useState("");
+  // Set when the server refuses a send over the cap, so the block shows at once rather than
+  // waiting for the next quota poll.
+  const [quotaReached, setQuotaReached] = useState<{ limit: number } | null>(null);
   const navigate = useNavigate();
   const location = useLocation();
   const toast = useToast();
@@ -128,6 +132,17 @@ export function DashboardAgentChat({
           .catch(() => null)) as { error?: string } | null;
         throw new Error(data?.error ?? MESSAGE_TOO_LARGE_ERROR);
       }
+      // Over the message cap: show the upgrade block instead of a generic turn error.
+      if (res.status === 403) {
+        const data = (await res
+          .clone()
+          .json()
+          .catch(() => null)) as { error?: string; limit?: number } | null;
+        if (data?.error === "message_quota_reached") {
+          setQuotaReached({ limit: data.limit ?? FREE_PLAN_MESSAGE_LIMIT });
+          throw new Error("You've reached your message limit.");
+        }
+      }
       return res;
     },
     clientData,
@@ -187,7 +202,10 @@ export function DashboardAgentChat({
 
   // Counted here, not in the panel, so it includes the turn just sent.
   const quota = useAgentMessageQuota({ actionPath, chatId, messages });
-  const atMessageCap = quota.kind === "reached";
+  // Either the poll saw the cap, or a send was just refused over it.
+  const atMessageCap = quota.kind === "reached" || quotaReached !== null;
+  const messageCapLimit =
+    quotaReached?.limit ?? (quota.kind === "reached" ? quota.limit : FREE_PLAN_MESSAGE_LIMIT);
 
   const isStreaming = status === "streaming";
   // From status, not the last part: the indicator must stay up through silent tool calls.
@@ -414,9 +432,9 @@ export function DashboardAgentChat({
         />
       )}
       {watchCard ? <div className="px-3 pb-2">{watchCard}</div> : null}
-      {quota.kind === "reached" ? (
+      {atMessageCap ? (
         <AgentUpgradeBlock
-          limit={quota.limit}
+          limit={messageCapLimit}
           context={
             <DashboardAgentContextBanner
               projectSlug={projectSlug}

apps/webapp/app/components/dashboard-agent/useAgentMessageQuota.ts

@@ -1,14 +1,18 @@
 import type { UIMessage } from "@ai-sdk/react";
 import { useEffect, useState } from "react";
+import { useCurrentPlan } from "~/routes/_app.orgs.$organizationSlug/route";
 import { countUserMessages, resolveMessageQuota, type MessageQuota } from "./message-quota";
 
-// Always undefined until billing supplies plan detection, which means no cap.
+// Gated on billing PRESENCE, not the plan value: no subscription means billing isn't wired
+// up (self-hosted), so there is no cap and no upgrade UI. A wired-up, non-paying plan is free.
 function useIsFreePlan(): boolean | undefined {
-  return undefined;
+  const subscription = useCurrentPlan()?.v3Subscription;
+  if (!subscription) return undefined;
+  return subscription.isPaying === false;
 }
 
-// Counted in two halves: the server aggregates other chats, this chat's own count
-// comes from the live transcript so the message just sent counts immediately.
+// `used` is the server's per-period count for the org. Re-read whenever the user sends, so
+// the running total tracks the message just sent without counting the transcript twice.
 export function useAgentMessageQuota({
   actionPath,
   chatId,
@@ -19,28 +23,24 @@ export function useAgentMessageQuota({
   messages: UIMessage[];
 }): MessageQuota {
   const isFreePlan = useIsFreePlan();
-  const [usedElsewhere, setUsedElsewhere] = useState<number | undefined>(undefined);
+  const [used, setUsed] = useState<number | undefined>(undefined);
+  const sentCount = countUserMessages(messages);
 
   useEffect(() => {
     if (isFreePlan !== true) return;
     const controller = new AbortController();
     void (async () => {
       try {
-        const res = await fetch(`${actionPath}?quota=1&chatId=${encodeURIComponent(chatId)}`, {
-          signal: controller.signal,
-        });
+        const res = await fetch(`${actionPath}?quota=1`, { signal: controller.signal });
         if (!res.ok) return;
         const data = (await res.json()) as { used?: number };
-        if (typeof data.used === "number") setUsedElsewhere(data.used);
+        if (typeof data.used === "number") setUsed(data.used);
       } catch {
         // Leave the count unknown, which means no cap. See `resolveMessageQuota`.
       }
     })();
     return () => controller.abort();
-  }, [isFreePlan, actionPath, chatId]);
+  }, [isFreePlan, actionPath, chatId, sentCount]);
 
-  return resolveMessageQuota({
-    isFreePlan,
-    used: usedElsewhere === undefined ? undefined : usedElsewhere + countUserMessages(messages),
-  });
+  return resolveMessageQuota({ isFreePlan, used });
 }

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.dashboard-agent.in.$.ts

@@ -15,6 +15,12 @@ import {
   resolveDashboardAgentRepoSnapshot,
 } from "~/services/dashboardAgent.server";
 import { dashboardAgentEnvironmentAddress } from "~/services/dashboardAgentEnvironmentAddress.server";
+import { dashboardAgentDb } from "~/services/dashboardAgentDb.server";
+import {
+  agentTurnCountsAgainstQuota,
+  recordAgentMessageSent,
+  resolveAgentMessageQuota,
+} from "~/services/dashboardAgentQuota.server";
 import { logger } from "~/services/logger.server";
 import { requireUser } from "~/services/session.server";
 import { readBoundedBodyText } from "~/utils/boundedRequestBody.server";
@@ -127,6 +133,17 @@ export async function action({ request, params }: ActionFunctionArgs) {
         return tooLarge();
       }
 
+      // Only a real user message consumes quota; action turns were refused above.
+      const countsAgainstQuota = agentTurnCountsAgainstQuota(parsed);
+      if (countsAgainstQuota) {
+        const quota = await resolveAgentMessageQuota(dashboardAgentDb, {
+          organizationId: project.organizationId,
+        });
+        if (quota?.reached) {
+          return json({ error: "message_quota_reached", limit: quota.limit }, { status: 403 });
+        }
+      }
+
       let userActorToken: string;
       try {
         userActorToken = await mintDashboardAgentUserActorToken(user.id, {
@@ -153,6 +170,12 @@ export async function action({ request, params }: ActionFunctionArgs) {
         ...(repoSnapshot ? { repoSnapshot } : {}),
       };
       body = JSON.stringify(parsed);
+
+      if (countsAgainstQuota) {
+        await recordAgentMessageSent(dashboardAgentDb, {
+          organizationId: project.organizationId,
+        });
+      }
     }
   }
 

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.dashboard-agent.ts

@@ -3,7 +3,7 @@ import {
   chatExists,
   countUnreadWatchWakes,
   countChatsWithUnreadWork,
-  countUserMessages,
+  getAgentMessageUsage,
   createChat,
   getChatMessages,
   getSession,
@@ -52,6 +52,11 @@ import {
 import { dashboardAgentEnvironmentAddress } from "~/services/dashboardAgentEnvironmentAddress.server";
 import { startDashboardAgentHeadStart } from "~/services/dashboardAgentHeadStart.server";
 import { dashboardAgentDb } from "~/services/dashboardAgentDb.server";
+import {
+  currentAgentMessagePeriod,
+  recordAgentMessageSent,
+  resolveAgentMessageQuota,
+} from "~/services/dashboardAgentQuota.server";
 import { logger } from "~/services/logger.server";
 import { resolveTriggerUri } from "~/services/resolveTriggerUri.server";
 import { requireUser } from "~/services/session.server";
@@ -150,13 +155,11 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
   const project = await findProjectBySlug(organizationSlug, projectParam, userId);
   if (!project) return json({ error: "Project not found" }, { status: 404 });
 
-  // The open chat is excluded and counted from the live transcript instead, so an
-  // unpersisted turn still counts against the cap.
+  // The per-period counter, org-wide: a deleted chat can't lower it within the period.
   if (searchParams.get("quota") === "1") {
-    const used = await countUserMessages(dashboardAgentDb, {
+    const used = await getAgentMessageUsage(dashboardAgentDb, {
       organizationId: project.organizationId,
-      userId,
-      excludeChatId: searchParams.get("chatId") ?? undefined,
+      period: currentAgentMessagePeriod(),
     });
     return json({ used });
   }
@@ -290,6 +293,13 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
       return messageTooLarge();
     }
 
+    const quota = await resolveAgentMessageQuota(dashboardAgentDb, {
+      organizationId: project.organizationId,
+    });
+    if (quota?.reached) {
+      return json({ error: "message_quota_reached", limit: quota.limit }, { status: 403 });
+    }
+
     let clientData: Record<string, unknown> | undefined;
     try {
       clientData = parsed.data.clientData
@@ -383,6 +393,14 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
         throw error;
       }
 
+      // Only the head start dispatches the first message here; a cold start sends it through
+      // the `in` proxy, which counts it there. Counting both would double-count.
+      if (headStarted) {
+        await recordAgentMessageSent(dashboardAgentDb, {
+          organizationId: project.organizationId,
+        });
+      }
+
       let publicAccessToken: string;
       try {
         publicAccessToken = await mintDashboardAgentToken(chatId);

apps/webapp/app/services/dashboardAgentQuota.server.ts

@@ -0,0 +1,100 @@
+import type { Limits } from "@trigger.dev/platform";
+import {
+  getAgentMessageUsage,
+  incrementAgentMessageUsage,
+  type DashboardAgentDb,
+} from "@internal/dashboard-agent-db";
+import { getCachedLimit } from "./platform.v3.server";
+import { logger } from "./logger.server";
+
+// The repo's unlimited sentinel. Never Infinity: it serializes to null in the limit cache.
+export const UNLIMITED_AGENT_MESSAGES = 100_000_000;
+
+// Filled by cloud billing (TRI-12863 P0). Absent until then, and always on self-hosted,
+// so the fallback applies and the cap is effectively off.
+const AGENT_MESSAGE_LIMIT_KEY = "agentMessages" as keyof Limits;
+
+/** The billing period the counter is scoped to: a UTC calendar month, "YYYY-MM". */
+export function currentAgentMessagePeriod(now: Date = new Date()): string {
+  return `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}`;
+}
+
+/** Pure so the send routes and, later, the MCP path share one rule. */
+export function checkAgentMessageQuota({ used, limit }: { used: number; limit: number }): {
+  reached: boolean;
+} {
+  return { reached: used >= limit };
+}
+
+export type AgentMessageQuota = { reached: boolean; used: number; limit: number };
+
+/**
+ * The period counter and the cached plan limit for one org. Fails open: an absent limit
+ * (self-hosted, or before the cloud side ships) resolves to the unlimited sentinel, and a
+ * counter read that throws returns `undefined` — either way there is no cap.
+ */
+export async function resolveAgentMessageQuota(
+  db: DashboardAgentDb,
+  params: {
+    organizationId: string;
+    now?: Date;
+    readLimit?: (organizationId: string) => Promise<number>;
+  }
+): Promise<AgentMessageQuota | undefined> {
+  const readLimit =
+    params.readLimit ??
+    (async (organizationId: string) => {
+      const cached = await getCachedLimit(
+        organizationId,
+        AGENT_MESSAGE_LIMIT_KEY,
+        UNLIMITED_AGENT_MESSAGES
+      );
+      // A cache error leaves `val` empty; fall open to unlimited.
+      return cached.val ?? UNLIMITED_AGENT_MESSAGES;
+    });
+  try {
+    const [limit, used] = await Promise.all([
+      readLimit(params.organizationId),
+      getAgentMessageUsage(db, {
+        organizationId: params.organizationId,
+        period: currentAgentMessagePeriod(params.now),
+      }),
+    ]);
+    return { ...checkAgentMessageQuota({ used, limit }), used, limit };
+  } catch (error) {
+    logger.error("Failed to resolve dashboard agent message quota", {
+      organizationId: params.organizationId,
+      error,
+    });
+    return undefined;
+  }
+}
+
+/** Record one sent user message. Swallows errors: the cap is a nudge, never a send blocker. */
+export async function recordAgentMessageSent(
+  db: DashboardAgentDb,
+  params: { organizationId: string; now?: Date }
+): Promise<void> {
+  try {
+    await incrementAgentMessageUsage(db, {
+      organizationId: params.organizationId,
+      period: currentAgentMessagePeriod(params.now),
+    });
+  } catch (error) {
+    logger.error("Failed to record a dashboard agent message against the quota", {
+      organizationId: params.organizationId,
+      error,
+    });
+  }
+}
+
+/**
+ * Whether an agent turn consumes quota. A wake/action turn is server-placed — the user never
+ * spent it — so only a `message` turn that is not an action counts. The `.in` proxy already
+ * refuses action turns; this keeps the rule explicit and testable.
+ */
+export function agentTurnCountsAgainstQuota(
+  turn: { kind?: string; payload?: { trigger?: string } } | undefined
+): boolean {
+  return turn?.kind === "message" && turn.payload?.trigger !== "action";
+}