feat(webapp): server-side agent message quota (#4552)

## What & why

The Free-plan agent-message allowance was only a client-side hint
(`useIsFreePlan()` was hardcoded to `undefined`, so nothing was
enforced) and the running count was a live `COUNT(*)` over
`chat_messages` — which meant deleting a chat silently freed quota. This
PR makes the allowance a real server-side limit with a durable counter,
so the cap holds regardless of the client and a deleted chat can't
reclaim messages within the period.

The cloud side that fills the actual per-plan number is a separate PR
(TRI-12863 P0). Until it deploys the `agentMessages` limit key is
absent, which resolves to the repo's unlimited sentinel — the correct
fail-open default, and why this ships independently.

## What's inside

- **New counter table** `trigger_dashboard_agent.agent_message_usage`,
keyed `(organization_id, period)` where `period` is a UTC calendar month
`"YYYY-MM"`. FK-free (`pgSchema` convention), plus a drizzle migration.
Deliberately **not** joined to chats — that closes the delete-a-chat
hole. Distinct from TRI-13068's `AiUsageEvent`; neither is derived from
the other.
- **New service** `dashboardAgentQuota.server.ts`: a pure
`checkAgentMessageQuota({ used, limit })` (so the MCP send path can
reuse the rule later) plus an org-scoped resolver that reads the period
counter and the cached plan limit, and a `recordAgentMessageSent`
increment.
- **Counting on send**: the create path (head start) and the `.in`
append path each increment one user message. The append path counts only
after the existing `trigger === "action"` 403, so **wakes never count**.
- **Enforcement**: at/over the limit both send routes return `403 {
error: "message_quota_reached", limit }`, which the client renders as
`AgentUpgradeBlock` rather than a generic failure. Never a silent drop.
- **Client**: `?quota=1` now reads the period counter; `useIsFreePlan()`
is a real read gated on **billing presence** (no subscription →
self-hosted → no cap, no upgrade UI), not on the plan value.

## Key decisions

- **Fails open.** The cap is a nudge, not a security boundary. An absent
limit (self-hosted, or pre-P0) resolves to the unlimited sentinel
`100_000_000` (never `Infinity` — that serializes to `null` in the Redis
limit cache), and a counter read that throws returns "no cap".
Self-hosted needs zero extra branching — it falls out of the fallback,
with a test to prove it.
- **Billing-presence gate.** The upgrade UI keys off whether a
subscription exists, so a self-hosted install with no billing shows no
cap and no upsell label.
- **The `(org, period)` table closes the delete hole.** A standalone
counter, not a count over chat rows, so deleting a chat can't free quota
inside the period.

## Testing

`apps/webapp/test/dashboardAgentQuota.test.ts` (testcontainers, no
mocks):
- pure `checkAgentMessageQuota` under/at/over/unlimited (control-breaks
the `>=`);
- `agentTurnCountsAgainstQuota` counts a message but not a wake
(control-breaks the wake exclusion);
- the counter accumulates and a **deleted chat can't free quota** within
the period; other periods/orgs start fresh;
- the resolver reports reached over the limit and never reached when
unlimited;
- fails open when the limit is absent (self-hosted) and when the counter
read throws.

`TRI-12863`

Author: kathiekiwi

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

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+The dashboard agent now comes with a monthly message allowance. A message that fails to send doesn't count against it.

.server-changes/agent-watch-plan-limits.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: feature
+---
+
+Watches now respect your plan's limits: free plans can run a limited number of watches at once and for a shorter window, with a prompt to upgrade for more.

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

@@ -1,9 +1,10 @@
 import { Link } from "@remix-run/react";
+import { AgentMonoLogo } from "~/components/primitives/AgentDotMatrix";
 import { LinkButton } from "~/components/primitives/Buttons";
 import { useOrganization } from "~/hooks/useOrganizations";
-import { cn } from "~/utils/cn";
 import { v3BillingPath } from "~/utils/pathBuilder";
-import { AgentIcon, AGENT_ICON_ACCENT_CLASS, ASK_AGENT_LABEL } from "./agent-identity";
+import { ASK_AGENT_LABEL } from "./agent-identity";
+import { messageQuotaReachedCopy } from "./message-quota";
 
 // Matches the composer's outer geometry so the replacement lands in the same place.
 const SLOT = "flex shrink-0 flex-col bg-background-bright px-3 pb-3 pt-1";
@@ -22,14 +23,12 @@ export function AgentUpgradeBlock({
       {context}
       <div className="mt-1.5 flex flex-col gap-2 rounded-md border border-border-bright bg-background-dimmed p-3">
         <div className="flex items-center gap-1.5">
-          <AgentIcon className={cn("size-4 shrink-0", AGENT_ICON_ACCENT_CLASS)} />
+          <AgentMonoLogo size={16} decorative className="shrink-0" />
           <span className="text-sm font-medium text-text-bright">
             Upgrade to unlock {ASK_AGENT_LABEL}
           </span>
         </div>
-        <p className="text-xs text-text-dimmed">
-          You've used all {limit} messages included on the Free plan. Your chats stay here to read.
-        </p>
+        <p className="text-xs text-text-dimmed">{messageQuotaReachedCopy(limit)}</p>
         <LinkButton variant="primary/small" to={v3BillingPath(organization)} fullWidth>
           Upgrade
         </LinkButton>

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, parseQuotaReachedResponse } 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,18 @@ 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;
+        const reached = parseQuotaReachedResponse(res.status, data);
+        if (reached) {
+          setQuotaReached(reached);
+          throw new Error("You've reached your message limit.");
+        }
+      }
       return res;
     },
     clientData,
@@ -185,9 +201,12 @@ export function DashboardAgentChat({
   const orderRef = useRef(createTranscriptOrder(initialMessages));
   const messages = orderTranscript(rawMessages, orderRef.current);
 
-  // Counted here, not in the panel, so it includes the turn just sent.
-  const quota = useAgentMessageQuota({ actionPath, chatId, messages });
-  const atMessageCap = quota.kind === "reached";
+  // Read here, not in the panel, so it re-reads as each turn settles.
+  const quota = useAgentMessageQuota({ actionPath, chatId, status });
+  // 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.
@@ -252,6 +271,8 @@ export function DashboardAgentChat({
   }, [sendRequest, submit, canSend]);
 
   const retry = useCallback(() => {
+    // Over the cap, a retry only earns another 403 — same guard as `submit`.
+    if (atMessageCap) return;
     // A watch's consent record is a user message nobody typed, so retry never treats it as one.
     const action = retryAction(
       messages.filter((m) => !(m.role === "user" && isWatchRequestMessageId(m.id)))
@@ -264,7 +285,7 @@ export function DashboardAgentChat({
       return;
     }
     void sendMessage({ text: action.text, messageId: action.messageId });
-  }, [messages, sendMessage, regenerate, clearError]);
+  }, [messages, sendMessage, regenerate, clearError, atMessageCap]);
 
   const resolveUri = useTriggerUriResolver(actionPath);
 
@@ -414,9 +435,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/DashboardAgentDraft.tsx

@@ -1,5 +1,6 @@
 import type { SuggestedPrompt } from "@internal/dashboard-agent-contracts";
 import { useCallback, useMemo, useState } from "react";
+import { AgentUpgradeBlock } from "./AgentUpgradeGate";
 import { DashboardAgentComposer } from "./DashboardAgentComposer";
 import { DashboardAgentContextBanner } from "./DashboardAgentContextBanner";
 import { DashboardAgentHero } from "./DashboardAgentHero";
@@ -16,6 +17,7 @@ export function DashboardAgentDraft({
   pageContext,
   promotedPrompt,
   watchCard,
+  capReached,
 }: {
   onSubmit: (text: string) => void;
   projectSlug: string;
@@ -24,6 +26,7 @@ export function DashboardAgentDraft({
   pageContext?: AgentPageContext;
   promotedPrompt?: SuggestedPrompt;
   watchCard?: React.ReactNode;
+  capReached?: { limit: number } | null;
 }) {
   const [input, setInput] = useState("");
 
@@ -43,12 +46,14 @@ export function DashboardAgentDraft({
 
   const submit = useCallback(
     (text: string) => {
+      // Suggested prompts reach here via the hero, bypassing the composer's cap guard.
+      if (capReached) return;
       const trimmed = text.trim();
       if (!trimmed) return;
       setInput("");
       onSubmit(trimmed);
     },
-    [onSubmit]
+    [onSubmit, capReached]
   );
 
   return (
@@ -57,25 +62,41 @@ export function DashboardAgentDraft({
       pageContext={pageContext}
       promoted={promotedPrompt}
       composer={
-        <div className="flex w-full flex-col gap-3">
-          {watchCard}
-          <DashboardAgentComposer
-            layout="hero"
-            value={input}
-            onChange={setInput}
-            onSubmit={() => submit(input)}
-            onStop={() => {}}
-            isStreaming={false}
-            placeholderSuggestion={watchCard ? undefined : placeholderSuggestion}
-            context={
-              <DashboardAgentContextBanner
-                projectSlug={projectSlug}
-                environmentSlug={environmentSlug}
-                currentPage={currentPage}
-              />
-            }
-          />
-        </div>
+        capReached ? (
+          <div className="flex w-full flex-col gap-3">
+            {watchCard}
+            <AgentUpgradeBlock
+              limit={capReached.limit}
+              context={
+                <DashboardAgentContextBanner
+                  projectSlug={projectSlug}
+                  environmentSlug={environmentSlug}
+                  currentPage={currentPage}
+                />
+              }
+            />
+          </div>
+        ) : (
+          <div className="flex w-full flex-col gap-3">
+            {watchCard}
+            <DashboardAgentComposer
+              layout="hero"
+              value={input}
+              onChange={setInput}
+              onSubmit={() => submit(input)}
+              onStop={() => {}}
+              isStreaming={false}
+              placeholderSuggestion={watchCard ? undefined : placeholderSuggestion}
+              context={
+                <DashboardAgentContextBanner
+                  projectSlug={projectSlug}
+                  environmentSlug={environmentSlug}
+                  currentPage={currentPage}
+                />
+              }
+            />
+          </div>
+        )
       }
     />
   );

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

@@ -24,6 +24,7 @@ import {
   writeLastChat,
 } from "./last-chat-storage";
 import { DashboardAgentDraft } from "./DashboardAgentDraft";
+import { parseQuotaReachedResponse } from "./message-quota";
 import { WatchCard } from "./WatchCard";
 import { watchDraftFor } from "./watch-card";
 import { NO_WATCH_CARD, watchCardReducer } from "./watch-card-state";
@@ -114,6 +115,8 @@ export function DashboardAgentPanel({
   // Until the list has arrived, the page load's server count is the better answer.
   const [chatsLoaded, setChatsLoaded] = useState(false);
   const [active, setActive] = useState<ActiveChat | null>(null);
+  // A refused `create` over the cap: the draft shows the upgrade block instead of a raw toast.
+  const [capReached, setCapReached] = useState<{ limit: number } | null>(null);
   // Starts true so an `openWith` request waits for the restore instead of racing it.
   const [loading, setLoading] = useState(
     () => readLastChat(storageKey)?.path === location.pathname
@@ -260,14 +263,22 @@ export function DashboardAgentPanel({
           publicAccessToken?: string;
           headStarted?: boolean;
           error?: string;
+          limit?: number;
         };
         if (seq !== openChatRequestSeq.current) return;
         if (!res.ok || !data.chatId || !data.publicAccessToken) {
+          const reached = parseQuotaReachedResponse(res.status, data);
+          if (reached) {
+            setCapReached(reached);
+            setActive(null);
+            return;
+          }
           console.error(`Dashboard agent: failed to create chat (${res.status})`, data.error);
           toast.error(data.error ?? "We couldn't start that chat. Try again in a moment.");
           setActive(null);
           return;
         }
+        setCapReached(null);
         setActive({
           chatId: data.chatId,
           organizationId: organization.id,
@@ -309,6 +320,7 @@ export function DashboardAgentPanel({
     panelOrg.current = organization.id;
     claimChatSlot();
     setActive(null);
+    setCapReached(null);
     setLoading(false);
     setChats([]);
     setChatsLoaded(false);
@@ -634,6 +646,7 @@ export function DashboardAgentPanel({
             pageContext={pageContext}
             promotedPrompt={promotedPrompt}
             watchCard={watchCardElement}
+            capReached={capReached}
           />
         )}
       </AgentPanelColumn>

apps/webapp/app/components/dashboard-agent/message-quota.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from "vitest";
-import { countUserMessages, FREE_PLAN_MESSAGE_LIMIT, resolveMessageQuota } from "./message-quota";
+import {
+  countUserMessages,
+  FREE_PLAN_MESSAGE_LIMIT,
+  MESSAGE_QUOTA_REACHED_ERROR,
+  messageQuotaReachedCopy,
+  parseQuotaReachedResponse,
+  resolveMessageQuota,
+} from "./message-quota";
 
 describe("resolveMessageQuota", () => {
   it("caps a Free plan at the limit", () => {
@@ -42,6 +49,37 @@ describe("resolveMessageQuota", () => {
   });
 });
 
+describe("parseQuotaReachedResponse", () => {
+  it("maps a create/in 403 cap body to the limit", () => {
+    // Both the create path and the `in` transport refuse with this exact body.
+    expect(
+      parseQuotaReachedResponse(403, { error: MESSAGE_QUOTA_REACHED_ERROR, limit: 20 })
+    ).toEqual({ limit: 20 });
+  });
+
+  it("falls back to the free limit when the body omits it", () => {
+    expect(parseQuotaReachedResponse(403, { error: MESSAGE_QUOTA_REACHED_ERROR })).toEqual({
+      limit: FREE_PLAN_MESSAGE_LIMIT,
+    });
+  });
+
+  it("ignores other errors and non-403 statuses so they surface normally", () => {
+    expect(parseQuotaReachedResponse(403, { error: "something_else" })).toBeNull();
+    expect(parseQuotaReachedResponse(500, { error: MESSAGE_QUOTA_REACHED_ERROR })).toBeNull();
+    expect(parseQuotaReachedResponse(403, null)).toBeNull();
+  });
+});
+
+describe("messageQuotaReachedCopy", () => {
+  it("is a friendly sentence naming the limit, never the raw code", () => {
+    const copy = messageQuotaReachedCopy(20);
+    expect(copy).toContain("all 20 messages");
+    expect(copy).toContain("Free plan");
+    // Control break: if the mapping leaked the server code, this fails.
+    expect(copy).not.toContain(MESSAGE_QUOTA_REACHED_ERROR);
+  });
+});
+
 describe("countUserMessages", () => {
   it("counts only what the user sent", () => {
     expect(

apps/webapp/app/components/dashboard-agent/message-quota.ts

@@ -27,6 +27,28 @@ export function resolveMessageQuota({
     : { kind: "within", used, limit, remaining };
 }
 
+// The server code both the create and `in` paths refuse with. The client owns the copy,
+// so this code must never reach the UI as text.
+export const MESSAGE_QUOTA_REACHED_ERROR = "message_quota_reached";
+
+// Maps a 403 refusal body to the cap signal, or null for any other error. Both paths use
+// this so a `message_quota_reached` code routes to the upgrade block, never a raw toast.
+export function parseQuotaReachedResponse(
+  status: number,
+  data: { error?: string; limit?: number } | null | undefined
+): { limit: number } | null {
+  if (status === 403 && data?.error === MESSAGE_QUOTA_REACHED_ERROR) {
+    return { limit: data.limit ?? FREE_PLAN_MESSAGE_LIMIT };
+  }
+  return null;
+}
+
+// The upgrade block's sentence. Pure so the copy is asserted directly, and so the raw
+// server code can never be what the user reads.
+export function messageQuotaReachedCopy(limit: number): string {
+  return `You've used all ${limit} messages included on the Free plan. Your chats stay here to read.`;
+}
+
 // A watch's consent record is a user message the person never typed, so it is
 // excluded here exactly as the stored count excludes it.
 export function countUserMessages(messages: { role: string; id?: string }[]): number {