feat(account): add usage limit reset control

Author: mhulden

docs/app-server-events.md

@@ -166,12 +166,14 @@ These are v2 request methods CodexMonitor currently sends to Codex app-server:
 - `account/login/start`
 - `account/login/cancel`
 - `account/rateLimits/read`
+- `account/rateLimitResetCredit/consume`
 - `account/read`
 - `skills/list`
 - `app/list`
 
 Notes:
 - `turn/start` now forwards the optional `serviceTier` override (`"fast"` for `/fast`, `null` for default/off) alongside `model`, `effort`, and `collaborationMode`.
+- `account/rateLimits/read` may return snapshot-only `rateLimitResetCredits.availableCount`; `account/rateLimitResetCredit/consume` spends one earned reset with an idempotency key. Clients should refetch `account/rateLimits/read` after each consume attempt.
 
 ## Missing Client Requests (Codex v2 ClientRequest Methods)
 

src-tauri/src/bin/codex_monitor_daemon.rs

@@ -897,6 +897,19 @@ impl DaemonState {
         codex_core::account_rate_limits_core(&self.sessions, workspace_id).await
     }
 
+    async fn consume_rate_limit_reset_credit(
+        &self,
+        workspace_id: String,
+        idempotency_key: String,
+    ) -> Result<Value, String> {
+        codex_core::consume_rate_limit_reset_credit_core(
+            &self.sessions,
+            workspace_id,
+            idempotency_key,
+        )
+        .await
+    }
+
     async fn account_read(&self, workspace_id: String) -> Result<Value, String> {
         codex_core::account_read_core(&self.sessions, &self.workspaces, workspace_id).await
     }

src-tauri/src/bin/codex_monitor_daemon/rpc/codex.rs

@@ -392,6 +392,21 @@ pub(super) async fn try_handle(
             };
             Some(state.account_rate_limits(workspace_id).await)
         }
+        "consume_rate_limit_reset_credit" => {
+            let workspace_id = match parse_string(params, "workspaceId") {
+                Ok(value) => value,
+                Err(err) => return Some(Err(err)),
+            };
+            let idempotency_key = match parse_string(params, "idempotencyKey") {
+                Ok(value) => value,
+                Err(err) => return Some(Err(err)),
+            };
+            Some(
+                state
+                    .consume_rate_limit_reset_credit(workspace_id, idempotency_key)
+                    .await,
+            )
+        }
         "account_read" => {
             let workspace_id = match parse_string(params, "workspaceId") {
                 Ok(value) => value,

src-tauri/src/codex/mod.rs

@@ -731,6 +731,34 @@ pub(crate) async fn account_rate_limits(
     codex_core::account_rate_limits_core(&state.sessions, workspace_id).await
 }
 
+#[tauri::command]
+pub(crate) async fn consume_rate_limit_reset_credit(
+    workspace_id: String,
+    idempotency_key: String,
+    state: State<'_, AppState>,
+    app: AppHandle,
+) -> Result<Value, String> {
+    if remote_backend::is_remote_mode(&*state).await {
+        return remote_backend::call_remote(
+            &*state,
+            app,
+            "consume_rate_limit_reset_credit",
+            json!({
+                "workspaceId": workspace_id,
+                "idempotencyKey": idempotency_key,
+            }),
+        )
+        .await;
+    }
+
+    codex_core::consume_rate_limit_reset_credit_core(
+        &state.sessions,
+        workspace_id,
+        idempotency_key,
+    )
+    .await
+}
+
 #[tauri::command]
 pub(crate) async fn account_read(
     workspace_id: String,

src-tauri/src/lib.rs

@@ -273,6 +273,7 @@ pub fn run() {
             codex::read_agent_config_toml,
             codex::write_agent_config_toml,
             codex::account_rate_limits,
+            codex::consume_rate_limit_reset_credit,
             codex::account_read,
             codex::saved_auth_profiles_list,
             codex::saved_auth_profile_sync_current,

src-tauri/src/remote_backend/mod.rs

@@ -146,6 +146,7 @@ fn can_retry_after_disconnect(method: &str) -> bool {
     matches!(
         method,
         "account_rate_limits"
+            | "consume_rate_limit_reset_credit"
             | "account_read"
             | "apps_list"
             | "collaboration_mode_list"

src-tauri/src/shared/codex_core.rs

@@ -629,6 +629,25 @@ pub(crate) async fn account_rate_limits_core(
         .await
 }
 
+pub(crate) async fn consume_rate_limit_reset_credit_core(
+    sessions: &Mutex<HashMap<String, Arc<WorkspaceSession>>>,
+    workspace_id: String,
+    idempotency_key: String,
+) -> Result<Value, String> {
+    let idempotency_key = idempotency_key.trim();
+    if idempotency_key.is_empty() {
+        return Err("idempotencyKey is required".to_string());
+    }
+    let session = get_session_clone(sessions, &workspace_id).await?;
+    session
+        .send_request_for_workspace(
+            &workspace_id,
+            "account/rateLimitResetCredit/consume",
+            json!({ "idempotencyKey": idempotency_key }),
+        )
+        .await
+}
+
 pub(crate) async fn account_read_core(
     sessions: &Mutex<HashMap<String, Arc<WorkspaceSession>>>,
     workspaces: &Mutex<HashMap<String, WorkspaceEntry>>,

src/features/app/components/MainApp.tsx

@@ -80,6 +80,7 @@ import {
 import { useAppShellOrchestration } from "@app/orchestration/useLayoutOrchestration";
 import { normalizeCodexArgsInput } from "@/utils/codexArgsInput";
 import { subscribeTrayOpenThread } from "@services/events";
+import { consumeRateLimitResetCredit } from "@services/tauri";
 
 const SettingsView = lazy(() =>
   import("@settings/components/SettingsView").then((module) => ({
@@ -270,6 +271,7 @@ export default function MainApp() {
   >(() => {});
 
   const { errorToasts, dismissErrorToast } = useErrorToasts();
+  const [resettingUsageLimit, setResettingUsageLimit] = useState(false);
   const queueGitStatusRefreshRef = useRef<() => void>(() => {});
   const handleThreadMessageActivity = useCallback(() => {
     queueGitStatusRefreshRef.current();
@@ -732,6 +734,78 @@ export default function MainApp() {
     refreshAccountRateLimits,
     alertError,
   });
+  const handleResetUsageLimit = useCallback(async () => {
+    const workspaceId = activeWorkspaceId;
+    const availableCount = activeRateLimits?.rateLimitResetCredits?.availableCount ?? 0;
+    if (!workspaceId || availableCount <= 0 || resettingUsageLimit) {
+      return;
+    }
+
+    const confirmed = window.confirm(
+      "Use 1 reset credit to reset your Codex usage limit?",
+    );
+    if (!confirmed) {
+      return;
+    }
+
+    const idempotencyKey =
+      typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+        ? crypto.randomUUID()
+        : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+    setResettingUsageLimit(true);
+    addDebugEntry({
+      id: `${Date.now()}-client-rate-limit-reset`,
+      timestamp: Date.now(),
+      source: "client",
+      label: "account/rateLimitResetCredit/consume",
+      payload: { workspaceId, idempotencyKey },
+    });
+
+    try {
+      const response = await consumeRateLimitResetCredit(workspaceId, idempotencyKey);
+      addDebugEntry({
+        id: `${Date.now()}-server-rate-limit-reset`,
+        timestamp: Date.now(),
+        source: "server",
+        label: "account/rateLimitResetCredit/consume response",
+        payload: response,
+      });
+      const result =
+        response?.result && typeof response.result === "object"
+          ? response.result
+          : response;
+      const outcome = typeof result?.outcome === "string" ? result.outcome : null;
+      if (outcome === "noCredit") {
+        alertError("No reset credits are available.");
+      } else if (outcome === "nothingToReset") {
+        alertError("There is no active usage limit to reset.");
+      }
+      await refreshAccountRateLimits(workspaceId);
+    } catch (error) {
+      addDebugEntry({
+        id: `${Date.now()}-client-rate-limit-reset-error`,
+        timestamp: Date.now(),
+        source: "error",
+        label: "account/rateLimitResetCredit/consume error",
+        payload: error instanceof Error ? error.message : String(error),
+      });
+      alertError(
+        error instanceof Error
+          ? `Reset failed: ${error.message}`
+          : "Reset failed.",
+      );
+    } finally {
+      setResettingUsageLimit(false);
+    }
+  }, [
+    activeRateLimits?.rateLimitResetCredits?.availableCount,
+    activeWorkspaceId,
+    addDebugEntry,
+    alertError,
+    refreshAccountRateLimits,
+    resettingUsageLimit,
+  ]);
   const {
     newAgentDraftWorkspaceId,
     startingDraftThreadWorkspaceId,
@@ -1632,6 +1706,8 @@ export default function MainApp() {
     onSwitchAccount: handleSwitchAccount,
     onCancelSwitchAccount: handleCancelSwitchAccount,
     onActivateSavedProfile: handleActivateSavedProfile,
+    onResetUsageLimit: handleResetUsageLimit,
+    resettingUsageLimit,
     onDecision: handleApprovalDecision,
     onRemember: handleApprovalRemember,
     onUserInputSubmit: handleUserInputSubmit,

src/features/app/components/Sidebar.test.tsx

@@ -41,6 +41,8 @@ const baseProps = {
   onCancelSwitchAccount: vi.fn(),
   onActivateSavedProfile: vi.fn(),
   accountSwitching: false,
+  onResetUsageLimit: vi.fn(),
+  resettingUsageLimit: false,
   onOpenSettings: vi.fn(),
   onOpenDebug: vi.fn(),
   showDebugButton: false,
@@ -148,6 +150,7 @@ describe("Sidebar", () => {
             unlimited: false,
             balance: "120",
           },
+          rateLimitResetCredits: null,
           planType: "pro",
         }}
       />,
@@ -157,6 +160,38 @@ describe("Sidebar", () => {
     expect(creditsLabel.textContent ?? "").toContain("120");
   });
 
+  it("shows reset credits and invokes the reset action", () => {
+    const onResetUsageLimit = vi.fn();
+    render(
+      <Sidebar
+        {...baseProps}
+        activeWorkspaceId="ws-1"
+        onResetUsageLimit={onResetUsageLimit}
+        accountRateLimits={{
+          primary: {
+            usedPercent: 62,
+            windowDurationMins: 300,
+            resetsAt: Math.round(Date.now() / 1000) + 3600,
+          },
+          secondary: null,
+          credits: null,
+          rateLimitResetCredits: {
+            availableCount: 2,
+          },
+          planType: "pro",
+        }}
+      />,
+    );
+
+    expect(screen.getByText("2 resets")).toBeTruthy();
+    const resetButton = screen.getByRole("button", { name: "Reset usage limit" });
+    expect((resetButton as HTMLButtonElement).disabled).toBe(false);
+
+    fireEvent.click(resetButton);
+
+    expect(onResetUsageLimit).toHaveBeenCalledTimes(1);
+  });
+
   it("opens the account menu from the bottom rail", () => {
     render(
       <Sidebar

src/features/app/components/Sidebar.tsx

@@ -129,6 +129,8 @@ type SidebarProps = {
   onCancelSwitchAccount: () => void;
   onActivateSavedProfile: (profileId: string) => void;
   accountSwitching: boolean;
+  onResetUsageLimit: () => void;
+  resettingUsageLimit: boolean;
   onOpenSettings: () => void;
   onOpenDebug: () => void;
   showDebugButton: boolean;
@@ -194,6 +196,8 @@ export const Sidebar = memo(function Sidebar({
   onCancelSwitchAccount,
   onActivateSavedProfile,
   accountSwitching,
+  onResetUsageLimit,
+  resettingUsageLimit,
   onOpenSettings,
   onOpenDebug,
   showDebugButton,
@@ -268,6 +272,7 @@ export const Sidebar = memo(function Sidebar({
     sessionResetLabel,
     weeklyResetLabel,
     creditsLabel,
+    resetCreditsLabel,
     showWeekly,
   } = getUsageLabels(accountRateLimits, usageShowRemaining);
   const debouncedQuery = useDebouncedValue(searchQuery, 150);
@@ -1042,7 +1047,15 @@ export const Sidebar = memo(function Sidebar({
         sessionResetLabel={sessionResetLabel}
         weeklyResetLabel={weeklyResetLabel}
         creditsLabel={creditsLabel}
+        resetCreditsLabel={resetCreditsLabel}
         showWeekly={showWeekly}
+        onResetUsageLimit={onResetUsageLimit}
+        resetUsageDisabled={
+          resettingUsageLimit ||
+          !activeWorkspaceId ||
+          !accountRateLimits?.rateLimitResetCredits?.availableCount
+        }
+        resettingUsageLimit={resettingUsageLimit}
         onOpenSettings={onOpenSettings}
         onOpenDebug={onOpenDebug}
         showDebugButton={showDebugButton}