Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

feat: allowance help

ogsamrat02f19db109a2
diff --git a/apps/app/src/app/lib/allowance-help.ts b/apps/app/src/app/lib/allowance-help.ts
new file mode 100644
index 00000000..7dc8e5a1
--- /dev/null
+++ b/apps/app/src/app/lib/allowance-help.ts
@@ -0,0 +1,137 @@
+// "How your allowance works" and "How to get a Good session": the help the
+// usage meter, the out-of-tokens card, the rewards panel and the Good-session
+// chip open. The same text is on omnirush.ai/guide (omnirush-ai.github.io,
+// web/src/guide.ts); change both together.
+//
+// Where each rule comes from (omnirush-backend unless noted):
+// day / week runtime_settings.grant_period_start/_end: a day is a UTC
+// day, the week an ISO week from Monday 00:00 UTC;
+// grant_parts (OmniRushDayAllowance, one row per UTC day)
+// parts grant_parts module doc: Discord and GitHub links, the
+// power credit (passing sessions of the last
+// power_window_days, up to power_cap), extras, pot
+// charged tokens gateway._record_tokens: uncached input, output,
+// reasoning and cache writes in full, cached input at
+// Settings.omnirush_cached_token_weight (0.25)
+// reservation grants.OmniRushGrantService.reserve/settle
+// rewards usable.reward_weight (power credit weights)
+// bands usable.band_of, session_dock (one band up per passing
+// session today; grace for new accounts / few sessions)
+// surcharge, pause session_dock (warn, surcharge refunded to the pot when
+// the session passes; cap for unrecorded sessions)
+// Good session good-session.ts (the live checklist) and the quality
+// dock's check texts (quality_controls texts)
+// Numbers an admin can change (amounts, caps, percents, multipliers) are not
+// written here: the app and the console show them from the server.
+
+export const ALLOWANCE_GUIDE_URL = "https://omnirush.ai/guide";
+export const ALLOWANCE_GUIDE_GOOD_SESSION_URL = `${ALLOWANCE_GUIDE_URL}#good-session`;
+
+export const ALLOWANCE_HELP_TITLE = "How your allowance works";
+export const ALLOWANCE_HELP_LINK = "How tokens work";
+export const GOOD_SESSION_HELP_TITLE = "How to get a Good session";
+
+export type HelpSection = { id: string; title: string; text?: string; points?: readonly string[] };
+
+/** Midnight UTC on the user's clock: "5:30 AM" (India), "8:00 PM" (New York, summer). */
+export function utcMidnightLocal(options: { timeZone?: string; now?: number } = {}): string {
+ const now = new Date(options.now ?? Date.now());
+ const midnight = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1);
+ return new Intl.DateTimeFormat("en-US", { hour: "numeric", minute: "2-digit", timeZone: options.timeZone }).format(midnight);
+}
+
+export const ALLOWANCE_SECTIONS: readonly HelpSection[] = Object.freeze([
+ {
+ id: "daily",
+ title: "Your daily tokens",
+ text: "You get a token allowance for each day, under a weekly cap. What is left shows in the sidebar and in Settings. Your daily tokens are the sum of:",
+ points: [
+ "Linked accounts: a linked Discord account and a linked GitHub account each add tokens every day. Link them on the console's Account page, which also shows when a link counts.",
+ "Good sessions: each session that passes the quality check adds tokens to every day for the next 7 days, up to a cap. Full, passing sessions add the most; sessions that pass but are cut off or very small add less.",
+ "Extras: approved project requests, referral and leaderboard bonuses and the like, while they last.",
+ ],
+ },
+ {
+ id: "reset",
+ title: "When it resets",
+ points: [
+ "Daily tokens refill at 00:00 UTC every day. The app shows the time on your clock next to the meter.",
+ "The weekly cap resets on Monday at 00:00 UTC. When the cap is reached, the daily tokens wait for it.",
+ "Unused daily tokens do not carry over to the next day.",
+ "Your bonus pot holds one-time tokens (for example sign-up tokens, refunds and prizes). It is used only when today's tokens or the weekly cap run out, and it does not refill on its own.",
+ ],
+ },
+ {
+ id: "usage",
+ title: "What uses tokens",
+ text: "Every request the agent sends to the model uses tokens: your message, the conversation so far, the files and tool results the agent reads, and its answer.",
+ points: [
+ "Input tokens: count in full.",
+ "Cached input: the part of the conversation the model already has from earlier turns counts at a quarter of its size.",
+ "Output tokens: the agent's answers, code and tool calls, in full.",
+ "Reasoning tokens: the model's thinking, in full. A higher reasoning effort uses more.",
+ "Sub-agents, automatic summaries and compaction are model requests too.",
+ "While a request runs, a small amount is held; when it ends, the real count replaces it.",
+ ],
+ },
+ {
+ id: "lower",
+ title: "What can lower it",
+ points: [
+ "Few passing sessions: if only a small share of your sessions from the last 7 days passes the quality check, your daily tokens are lowered to a percentage. The app shows a notice with the percent. Each session that passes today lifts you one step for the rest of the day. New accounts and accounts with only a few checked sessions keep their full allowance.",
+ "Sessions not uploaded: heavy use with few uploaded sessions can lower it too. Keep the app updated and recording on.",
+ "Quality tier: while your tier is Limited, your tokens are reduced. The tier badge next to your name shows by how much when you point at it.",
+ "Off-track sessions: a session that is clearly off track (not recorded, most tool calls failing, or no project and no code changed) gets a warning first. If it carries on, its tokens cost more. If it passes the quality check in the end, the extra comes back to your bonus pot.",
+ "Paused session: a session that is not being recorded is paused after a set amount. Update OmniRush or turn recording back on, then start a new session. Your other sessions keep working.",
+ ],
+ },
+ {
+ id: "save",
+ title: "Spending less",
+ points: [
+ "Start a new session for a new task: every turn sends the conversation again, so long chats cost more per turn.",
+ "Use a lower reasoning effort for simple changes.",
+ "Point the agent at the files that matter instead of asking it to read the whole project.",
+ ],
+ },
+]);
+
+export const GOOD_SESSION_SECTIONS: readonly HelpSection[] = Object.freeze([
+ {
+ id: "steps",
+ title: "The checklist",
+ text: "The Good session chip above the message box checks these as you work. The star fills in after the server's check, once the session has uploaded.",
+ points: [
+ "In a project: open a real project folder before you start, not your home folder, Desktop or Downloads, and keep every edit inside it.",
+ "Code changed: build or change real code, at least 2 code files and 30 lines, or 5 files and 150 lines. Docs, images, lock files and build output don't count.",
+ "Ran or tested: have the agent build it, run it or run its tests (a test runner, compiler, linter or type check).",
+ "Finished: let the last turn finish with the agent's answer. If it asks you something, answer it. If a turn stops early, send \"continue\".",
+ ],
+ },
+ {
+ id: "work",
+ title: "Real work counts",
+ points: [
+ "Debugging, a feature, a refactor, performance or build work count most. Chats, read-only questions, coding puzzles and tutorial projects count less or not at all.",
+ "Two real turns, or one long one. If a session is short, send one more follow-up.",
+ "Few errors: if most tool calls fail, fix the setup (paths, dependencies) or ask the agent to step back.",
+ ],
+ },
+ {
+ id: "local",
+ title: "Keep it local",
+ points: [
+ "Work with local code and test data. Cloud tools (gh, aws, vercel and the like), remote git (clone, pull, push), Docker, remote databases and web pages fail the project check.",
+ "Avoid programs only your machine has (osascript, systemctl, adb and the like).",
+ "If the agent calls a local dev server, start it in the same session.",
+ ],
+ },
+ {
+ id: "recording",
+ title: "Keep recording on",
+ points: [
+ "Every turn uploads. Keep the app updated and recording on: a session that isn't recorded can't count.",
+ "Don't quit while a turn is running or has just failed; the app asks before it lets you.",
+ ],
+ },
+]);
diff --git a/apps/app/src/components/chat/message-list.tsx b/apps/app/src/components/chat/message-list.tsx
index f462f8c8..1e6b3075 100644
--- a/apps/app/src/components/chat/message-list.tsx
+++ b/apps/app/src/components/chat/message-list.tsx
@@ -34,6 +34,8 @@ import { t } from "@/i18n"
import { useOpenTargets } from "@/lib/target-provider"
import { openTargetFromUrl } from "@/react-app/domains/session/artifacts/open-target"
import { sessionErrorPresentationFromUIMessage } from "@/react-app/domains/session/sync/session-error"
+import { gatewayRefusalEvent } from "@/app/lib/gateway-refusal"
+import { AllowanceHelpLink } from "@/react-app/domains/quality/allowance-help"
import { ApplyPatchTool } from "@/components/tools/apply-patch"
import { BashTool } from "@/components/tools/bash"
import { ComputerUseToolLine } from "@/components/tools/computer-use"
@@ -876,6 +878,7 @@ const MessageComponent = React.memo(
resumePrompt={presentation?.recoveryPrompt}
technicalDetails={presentation?.technicalDetails}
action={presentation?.action}
+ allowanceHelp={isAllowanceLimit(presentation)}
/>
)
}
@@ -975,6 +978,8 @@ interface ErrorMessageProps {
technicalDetails?: string | null
/** A page that fixes the error ("Open console"), opened in the browser. */
action?: { label: string; link: string } | null
+ /** An out-of-tokens or paused-session refusal: link the allowance help. */
+ allowanceHelp?: boolean
}
/**
@@ -1039,7 +1044,13 @@ function SessionErrorTechnicalDetails({ details, tone }: { details: string; tone
)
}
-function ErrorMessage({ error, description, showDescriptionOnResume, resumePrompt, technicalDetails, action }: ErrorMessageProps) {
+/** Whether a session error is omnirush.ai's allowance (tokens used up, weekly cap) or a paused session. */
+function isAllowanceLimit(presentation: Parameters<typeof gatewayRefusalEvent>[0]): boolean {
+ const limit = gatewayRefusalEvent(presentation)?.properties.limit_type
+ return limit === "tokens" || limit === "session_cap"
+}
+
+function ErrorMessage({ error, description, showDescriptionOnResume, resumePrompt, technicalDetails, action, allowanceHelp }: ErrorMessageProps) {
const { onResumeInterrupted, developerMode } = useMessageList()
// Status codes, provider names, and response bodies are for developers,
// admins, and support — not the plain-language card end users see. They
@@ -1100,6 +1111,7 @@ function ErrorMessage({ error, description, showDescriptionOnResume, resumePromp
{action.label}
</Button>
) : null}
+ {allowanceHelp ? <AllowanceHelpLink className="mt-0.5 w-fit" testId="session-error-allowance-help" /> : null}
</div>
</div>
{details ? <SessionErrorTechnicalDetails details={details} tone="card" /> : null}
diff --git a/apps/app/src/react-app/domains/quality/allowance-help.tsx b/apps/app/src/react-app/domains/quality/allowance-help.tsx
new file mode 100644
index 00000000..a1ede8fa
--- /dev/null
+++ b/apps/app/src/react-app/domains/quality/allowance-help.tsx
@@ -0,0 +1,139 @@
+/** @jsxImportSource react */
+import { CircleHelp, ExternalLink } from "lucide-react";
+import { create } from "zustand";
+
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from "@/components/ui/dialog";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { cn } from "@/lib/utils";
+
+import {
+ ALLOWANCE_GUIDE_GOOD_SESSION_URL,
+ ALLOWANCE_GUIDE_URL,
+ ALLOWANCE_HELP_LINK,
+ ALLOWANCE_HELP_TITLE,
+ ALLOWANCE_SECTIONS,
+ GOOD_SESSION_HELP_TITLE,
+ GOOD_SESSION_SECTIONS,
+ utcMidnightLocal,
+ type HelpSection,
+} from "../../../app/lib/allowance-help";
+import { openDesktopUrl } from "../../../app/lib/desktop";
+import { omnirushUsageSummary } from "../../../app/lib/omnirush-usage";
+import { useAccountStatusStore } from "../../../app/lib/quality";
+
+export type AllowanceHelpTab = "allowance" | "good-session";
+
+type AllowanceHelpStore = {
+ tab: AllowanceHelpTab | null;
+ open: (tab?: AllowanceHelpTab) => void;
+ close: () => void;
+};
+
+/** Which tab of the help is open (null: closed); any surface can open it. */
+export const useAllowanceHelpStore = create<AllowanceHelpStore>((set) => ({
+ tab: null,
+ open: (tab = "allowance") => set({ tab }),
+ close: () => set({ tab: null }),
+}));
+
+export function openAllowanceHelp(tab: AllowanceHelpTab = "allowance") {
+ useAllowanceHelpStore.getState().open(tab);
+}
+
+function Sections({ sections }: { sections: readonly HelpSection[] }) {
+ return (
+ <>
+ {sections.map((section) => (
+ <section key={section.id} data-help-section={section.id} className="space-y-1.5">
+ <h3 className="text-[13px] font-medium text-foreground">{section.title}</h3>
+ {section.text ? <p className="text-xs leading-5 text-muted-foreground">{section.text}</p> : null}
+ {section.points?.length ? (
+ <ul className="list-disc space-y-1 ps-4 text-xs leading-5 text-muted-foreground marker:text-muted-foreground/60">
+ {section.points.map((point) => <li key={point}>{point}</li>)}
+ </ul>
+ ) : null}
+ </section>
+ ))}
+ </>
+ );
+}
+
+/** The help body: the account's own line, then the two tabs (also rendered by the tests). */
+export function AllowanceHelpBody(props: {
+ tab: AllowanceHelpTab;
+ onTabChange?: (tab: AllowanceHelpTab) => void;
+ usageLine?: string | null;
+ resetLocal?: string;
+}) {
+ const reset = props.resetLocal ?? utcMidnightLocal();
+ return (
+ <Tabs value={props.tab} onValueChange={(value) => props.onTabChange?.(value as AllowanceHelpTab)} className="min-h-0 gap-3">
+ <TabsList className="w-full">
+ <TabsTrigger value="allowance" data-testid="allowance-help-tab-allowance">Your tokens</TabsTrigger>
+ <TabsTrigger value="good-session" data-testid="allowance-help-tab-good-session">Good session</TabsTrigger>
+ </TabsList>
+ <TabsContent value="allowance" className="space-y-4">
+ <div className="rounded-xl border border-border px-3 py-2 text-xs leading-5" data-testid="allowance-help-now">
+ {props.usageLine ? <p className="text-foreground">{props.usageLine}</p> : null}
+ <p className="text-muted-foreground">
+ Daily tokens refill at 00:00 UTC, which is {reset} on your clock.
+ </p>
+ </div>
+ <Sections sections={ALLOWANCE_SECTIONS} />
+ </TabsContent>
+ <TabsContent value="good-session" className="space-y-4">
+ <Sections sections={GOOD_SESSION_SECTIONS} />
+ </TabsContent>
+ </Tabs>
+ );
+}
+
+/** The help dialog, mounted once over the app. */
+export function AllowanceHelpDialog() {
+ const tab = useAllowanceHelpStore((store) => store.tab);
+ const status = useAccountStatusStore((store) => store.status);
+ const usageLine = tab && status?.connected && status.usage ? omnirushUsageSummary(status.usage).line : null;
+ const link = tab === "good-session" ? ALLOWANCE_GUIDE_GOOD_SESSION_URL : ALLOWANCE_GUIDE_URL;
+ return (
+ <Dialog open={tab !== null} onOpenChange={(open) => { if (!open) useAllowanceHelpStore.getState().close(); }}>
+ <DialogContent className="gap-4 lg:max-w-lg" data-testid="allowance-help">
+ <div className="pe-8">
+ <DialogTitle className="text-base">{tab === "good-session" ? GOOD_SESSION_HELP_TITLE : ALLOWANCE_HELP_TITLE}</DialogTitle>
+ <DialogDescription className="text-xs">
+ How tokens are counted, when they reset, and how good sessions raise them.
+ </DialogDescription>
+ </div>
+ <div className="max-h-[60vh] overflow-y-auto pe-1">
+ {tab ? <AllowanceHelpBody tab={tab} usageLine={usageLine} onTabChange={(next) => useAllowanceHelpStore.getState().open(next)} /> : null}
+ </div>
+ <button
+ type="button"
+ data-testid="allowance-help-guide"
+ onClick={() => void openDesktopUrl(link)}
+ className="inline-flex w-fit items-center gap-1 text-xs text-muted-foreground underline-offset-2 transition hover:text-foreground hover:underline"
+ >
+ Read the full guide on omnirush.ai
+ <ExternalLink className="size-3" aria-hidden="true" />
+ </button>
+ </DialogContent>
+ </Dialog>
+ );
+}
+
+/** A small text link that opens the help ("How tokens work"). */
+export function AllowanceHelpLink(props: { tab?: AllowanceHelpTab; label?: string; className?: string; testId?: string }) {
+ return (
+ <button
+ type="button"
+ data-testid={props.testId ?? "allowance-help-link"}
+ onClick={() => openAllowanceHelp(props.tab)}
+ className={cn(
+ "inline-flex items-center gap-1 text-xs text-muted-foreground underline-offset-2 transition hover:text-foreground hover:underline",
+ props.className,
+ )}
+ >
+ <CircleHelp className="size-3 shrink-0" aria-hidden="true" />
+ {props.label ?? ALLOWANCE_HELP_LINK}
+ </button>
+ );
+}
diff --git a/apps/app/src/react-app/domains/quality/good-session.tsx b/apps/app/src/react-app/domains/quality/good-session.tsx
index 35380eb7..77c5a4d3 100644
--- a/apps/app/src/react-app/domains/quality/good-session.tsx
+++ b/apps/app/src/react-app/domains/quality/good-session.tsx
@@ -63,6 +63,7 @@ import {
} from "../../../app/lib/good-session-integrity";
import type { OmniRushGoodSession, OmniRushServerClient } from "../../../app/lib/omnirush-server";
import { readPref, useAccountQuality, writePref } from "../../../app/lib/quality";
+import { AllowanceHelpLink } from "./allowance-help";
import { isDesktopRuntime } from "../../../app/utils";
import { hasLiveSessionActivity, useSessionActivityStore } from "../session/status/session-activity-store";
@@ -609,6 +610,7 @@ export function GoodSessionChecklistBar(props: GoodSessionChecklistBarProps) {
</PopoverTrigger>
<PopoverContent side="top" align="end" className="w-72 gap-2 rounded-2xl p-3">
<GoodSessionGuide />
+ <AllowanceHelpLink tab="good-session" label="The full guide" testId="good-session-full-guide" />
</PopoverContent>
</Popover>
</div>
diff --git a/apps/app/src/react-app/domains/quality/quality-notice.tsx b/apps/app/src/react-app/domains/quality/quality-notice.tsx
index 6cadcd4f..32d8a080 100644
--- a/apps/app/src/react-app/domains/quality/quality-notice.tsx
+++ b/apps/app/src/react-app/domains/quality/quality-notice.tsx
@@ -24,6 +24,7 @@ import { BiggestWinTicker, NextSpinHint, QualityTierBadge, StreakLine } from "./
import { QualitySpinDialog } from "./quality-spin-dialog";
import { useQualityPopups } from "./use-quality-popups";
import { GoodSessionGuide } from "./good-session";
+import { AllowanceHelpLink } from "./allowance-help";
import { goodSessionWording } from "../../../app/lib/good-session";
/** Used only when the server sends no `fail_labels` entry for a code. */
@@ -178,6 +179,7 @@ export function QualityNoticeCard(props: QualityNoticeCardProps) {
) : null}
<GoodSessionGuide className="rounded-lg border border-border px-3 py-2" />
+ <AllowanceHelpLink className="w-fit" testId="quality-notice-allowance-help" />
{coaching ? (
<div>
diff --git a/apps/app/src/react-app/domains/session/sidebar/app-sidebar.tsx b/apps/app/src/react-app/domains/session/sidebar/app-sidebar.tsx
index 268d7103..621dd8f5 100644
--- a/apps/app/src/react-app/domains/session/sidebar/app-sidebar.tsx
+++ b/apps/app/src/react-app/domains/session/sidebar/app-sidebar.tsx
@@ -37,6 +37,7 @@ import {
Workflow,
MessageCircleMore,
Sparkles,
+ CircleHelp,
} from "lucide-react";
import { LazyMotion, Reorder, domMax, m, useDragControls } from "motion/react";
@@ -47,6 +48,8 @@ import { isDesktopRuntime } from "../../../../app/lib/runtime-env";
import { refreshAccountStatus, setQualitySessionId, useAccountStatusStore, useQualityUiStore, type AccountQuality } from "../../../../app/lib/quality";
import { goodSessionWording } from "../../../../app/lib/good-session";
import { ProgressRing, QualityTierBadge, SpinCounts, spinRowTitle } from "../../quality/quality-parts";
+import { openAllowanceHelp } from "../../quality/allowance-help";
+import { ALLOWANCE_HELP_TITLE } from "../../../../app/lib/allowance-help";
import { buildathonProjects, useBuildathonStore } from "../../../../app/lib/buildathon";
import { OmniRushDenHelpLink } from "../../workspace/omnirush-den-help-link";
import { NotificationBell } from "../../../shell/notification-center";
@@ -76,6 +79,7 @@ import {
SidebarHeader,
SidebarGroupContent,
SidebarMenu,
+ SidebarMenuAction,
SidebarMenuButton,
SidebarMenuItem,
SidebarFooter,
@@ -1101,7 +1105,7 @@ function NativeAccountFooter({ onOpenAccountSettings }: { onOpenAccountSettings:
<SidebarMenuItem>
<SidebarMenuButton
type="button"
- className="h-auto min-h-12 py-1.5"
+ className={cn("h-auto min-h-12 py-1.5", usage && "pe-7")}
onClick={onOpenAccountSettings}
tooltip={accountTooltip}
aria-label={connected ? `${accountLabel} account` : "Sign in to omnirush.ai"}
@@ -1132,6 +1136,18 @@ function NativeAccountFooter({ onOpenAccountSettings }: { onOpenAccountSettings:
) : null}
</span>
</SidebarMenuButton>
+ {usage ? (
+ <SidebarMenuAction
+ type="button"
+ onClick={() => openAllowanceHelp()}
+ title={ALLOWANCE_HELP_TITLE}
+ aria-label={ALLOWANCE_HELP_TITLE}
+ data-testid="native-account-allowance-help"
+ className="text-muted-foreground"
+ >
+ <CircleHelp />
+ </SidebarMenuAction>
+ ) : null}
</SidebarMenuItem>
{quality ? <QualitySpinRow quality={quality} /> : null}
{shellConfig.feedbackButton ? (
diff --git a/apps/app/src/react-app/domains/settings/pages/general-view.tsx b/apps/app/src/react-app/domains/settings/pages/general-view.tsx
index b885f409..47d1a90e 100644
--- a/apps/app/src/react-app/domains/settings/pages/general-view.tsx
+++ b/apps/app/src/react-app/domains/settings/pages/general-view.tsx
@@ -32,6 +32,8 @@ import {
import type { OmniRushApprovalMode, OmniRushRuntimeApprovals } from "../../../../app/lib/omnirush-server";
import { captureAnalyticsEvent, resetAnalyticsAccount, syncAnalyticsAccount } from "../../../../app/lib/analytics";
import { omnirushUsageSummary } from "../../../../app/lib/omnirush-usage";
+import { ALLOWANCE_HELP_TITLE } from "../../../../app/lib/allowance-help";
+import { AllowanceHelpLink } from "../../quality/allowance-help";
import { isElectronRuntime } from "../../../../app/utils";
import {
APPROVAL_MODES,
@@ -490,6 +492,9 @@ export function GeneralSettingsView(props: GeneralSettingsViewProps) {
/>
</div>
) : null}
+ {usage ? (
+ <AllowanceHelpLink className="mt-1.5 text-[11px] text-dls-secondary" label={ALLOWANCE_HELP_TITLE} testId="account-allowance-help" />
+ ) : null}
</div>
{account.connected ? (
<button type="button" disabled={accountBusy} onClick={() => void signOutAccount()} className="rounded-lg border border-dls-border px-3 py-2 text-[12px] text-dls-secondary hover:bg-dls-hover disabled:opacity-50">
diff --git a/apps/app/src/react-app/shell/app-root.tsx b/apps/app/src/react-app/shell/app-root.tsx
index cdb29664..2d3a67d9 100644
--- a/apps/app/src/react-app/shell/app-root.tsx
+++ b/apps/app/src/react-app/shell/app-root.tsx
@@ -50,6 +50,7 @@ import { DesktopUpdaterProvider } from "../domains/settings/state/desktop-update
import { SyncRestartGate } from "./sync-restart-banner";
import { UpdateGate } from "./update-gate";
import { QualityRewards } from "../domains/quality/quality-notice";
+import { AllowanceHelpDialog } from "../domains/quality/allowance-help";
import { BuildathonLayer } from "../domains/buildathon/buildathon";
import { BuildathonPromoGate } from "../domains/buildathon/buildathon-promo";
import { TurnRunningSync } from "../domains/quality/good-session";
@@ -530,6 +531,7 @@ export function AppRoot() {
<LoadingOverlay />
<CloudWorkspaceOverlay />
{isDesktopRuntime() ? <QualityRewards /> : null}
+ <AllowanceHelpDialog />
{isDesktopRuntime() ? <BuildathonLayer /> : null}
{isDesktopRuntime() ? <TurnRunningSync /> : null}
</CloudWorkspaceStatusProvider>
diff --git a/apps/app/tests/allowance-help.test.tsx b/apps/app/tests/allowance-help.test.tsx
new file mode 100644
index 00000000..9cfb5de4
--- /dev/null
+++ b/apps/app/tests/allowance-help.test.tsx
@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import {
+ ALLOWANCE_GUIDE_GOOD_SESSION_URL,
+ ALLOWANCE_GUIDE_URL,
+ ALLOWANCE_SECTIONS,
+ GOOD_SESSION_SECTIONS,
+ utcMidnightLocal,
+} from "../src/app/lib/allowance-help";
+import { FLOOR_ALONE_FILES, FLOOR_ALONE_LINES, FLOOR_FILES, FLOOR_LINES, GOOD_SESSION_GUIDE } from "../src/app/lib/good-session";
+import { AllowanceHelpBody, openAllowanceHelp, useAllowanceHelpStore } from "../src/react-app/domains/quality/allowance-help";
+
+const allText = (sections: typeof ALLOWANCE_SECTIONS) =>
+ sections.flatMap((section) => [section.title, section.text ?? "", ...(section.points ?? [])]).join("\n");
+
+describe("allowance help content", () => {
+ test("midnight UTC on the user's clock", () => {
+ const now = Date.UTC(2026, 9, 21, 12, 0);
+ expect(utcMidnightLocal({ timeZone: "Asia/Kolkata", now })).toBe("5:30 AM");
+ expect(utcMidnightLocal({ timeZone: "America/New_York", now })).toBe("8:00 PM");
+ expect(utcMidnightLocal({ timeZone: "UTC", now })).toBe("12:00 AM");
+ });
+
+ test("states the fixed rules: UTC reset, Monday week, cached input share", () => {
+ const text = allText(ALLOWANCE_SECTIONS);
+ expect(text).toContain("00:00 UTC every day");
+ expect(text).toContain("Monday at 00:00 UTC");
+ expect(text).toContain("Cached input");
+ expect(text).toContain("a quarter of its size");
+ expect(text).toContain("Reasoning tokens");
+ });
+
+ test("hardcodes no admin-set token amounts", () => {
+ const text = allText(ALLOWANCE_SECTIONS) + allText(GOOD_SESSION_SECTIONS);
+ expect(text).not.toMatch(/\d+(\.\d+)?\s?[MK]\b/);
+ expect(text).not.toMatch(/\d+\s?%/);
+ expect(text).not.toMatch(/[x×]\s?\d/);
+ });
+
+ test("the Good-session part matches the live checklist", () => {
+ const text = allText(GOOD_SESSION_SECTIONS);
+ expect(text).toContain(`at least ${FLOOR_FILES} code files and ${FLOOR_LINES} lines, or ${FLOOR_ALONE_FILES} files and ${FLOOR_ALONE_LINES} lines`);
+ // Every step of the short guide is covered.
+ expect(GOOD_SESSION_GUIDE.length).toBe(4);
+ for (const label of ["In a project", "Code changed", "Ran or tested", "Finished"]) expect(text).toContain(label);
+ });
+
+ test("links to the site guide", () => {
+ expect(ALLOWANCE_GUIDE_URL).toBe("https://omnirush.ai/guide");
+ expect(ALLOWANCE_GUIDE_GOOD_SESSION_URL).toBe("https://omnirush.ai/guide#good-session");
+ });
+});
+
+describe("allowance help dialog", () => {
+ test("the store opens a tab and closes", () => {
+ openAllowanceHelp();
+ expect(useAllowanceHelpStore.getState().tab).toBe("allowance");
+ openAllowanceHelp("good-session");
+ expect(useAllowanceHelpStore.getState().tab).toBe("good-session");
+ useAllowanceHelpStore.getState().close();
+ expect(useAllowanceHelpStore.getState().tab).toBeNull();
+ });
+
+ test("the tokens tab shows the account line and the local reset", () => {
+ const html = renderToStaticMarkup(
+ <AllowanceHelpBody tab="allowance" usageLine="3.2M of 10M tokens left today" resetLocal="5:30 AM" />,
+ );
+ expect(html).toContain("3.2M of 10M tokens left today");
+ expect(html).toContain("Daily tokens refill at 00:00 UTC, which is 5:30 AM on your clock.");
+ for (const section of ALLOWANCE_SECTIONS) expect(html).toContain(section.title);
+ });
+
+ test("the Good-session tab lists the checklist", () => {
+ const html = renderToStaticMarkup(<AllowanceHelpBody tab="good-session" resetLocal="5:30 AM" />);
+ for (const section of GOOD_SESSION_SECTIONS) expect(html).toContain(section.title);
+ });
+});