@moondeck/station 0.0.1 → 1.0.1

package/lib/agents/cursor-period-usage.ts

@@ -0,0 +1,253 @@
+/**
+ * Cursor account room, read from the same dashboard calls the CLI's `/usage`
+ * screen uses. The headless stream does not report it.
+ *
+ * The CLI session access token (not the user API key, and not a team admin
+ * key) calls `aiserver.v1.DashboardService/GetPlanInfo` and
+ * `GetCurrentPeriodUsage` on api2.cursor.sh. A failure, a missing token, or a
+ * shape we do not recognise produces no report. Nothing here logs the token,
+ * an email, or a user id.
+ */
+
+import type { TaskEnvironmentAgentSessionSurface } from "../task-environment/types";
+import type { AgentAccountUsage } from "./types";
+
+/** Same lines Codex uses for a window that is full or close to full. */
+export const CURSOR_PERIOD_WARNING_PERCENT = 90;
+export const CURSOR_PERIOD_LIMITED_PERCENT = 100;
+
+/** One probe per leased credential, including a failed one. */
+export const CURSOR_PERIOD_PROBE_INTERVAL_MS = 5 * 60 * 1000;
+
+/** One bound for the whole probe: reading auth.json and both dashboard calls.
+ *  A hung read must not hold turn_complete after the CLI has finished. */
+export const CURSOR_PERIOD_PROBE_TIMEOUT_MS = 4_000;
+
+export const CURSOR_PERIOD_USAGE_LOG = "cursor period usage unavailable";
+
+export const CURSOR_AUTH_JSON = "/home/node/.config/cursor/auth.json";
+
+const DASHBOARD_ORIGIN = "https://api2.cursor.sh";
+const WEEKLY_PERIOD = "INCLUDED_USAGE_PERIOD_WEEKLY";
+const WEEK_MINUTES = 7 * 24 * 60;
+
+const probedAt = new Map<string, number>();
+
+/** Whether this credential may be probed at `now`. */
+export function cursorPeriodProbeDue(credentialId: string, now: number): boolean {
+  const at = probedAt.get(credentialId);
+  return at === undefined || now - at >= CURSOR_PERIOD_PROBE_INTERVAL_MS;
+}
+
+/** Count a probe, successful or not, so the next one waits out the interval. */
+export function markCursorPeriodProbed(credentialId: string, now: number): void {
+  probedAt.set(credentialId, now);
+}
+
+/** Test hook. Production never clears the gate except by process restart. */
+export function resetCursorPeriodProbes(): void {
+  probedAt.clear();
+}
+
+/** The CLI session access token from `auth.json`, or null. The raw file is not returned. */
+export function cursorAccessTokenFromAuthJson(text: string): string | null {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const token = (parsed as { accessToken?: unknown }).accessToken;
+    return typeof token === "string" && token.length > 0 ? token : null;
+  } catch {
+    return null;
+  }
+}
+
+function isObj(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function epochMs(value: unknown): number | undefined {
+  const n =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && /^[0-9]+$/.test(value)
+        ? Number(value)
+        : Number.NaN;
+  return Number.isSafeInteger(n) && n > 0 ? n : undefined;
+}
+
+/** A 0–100 share, as the dashboard sends it. Anything else is not a window. */
+function percent(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 100) {
+    return undefined;
+  }
+  return value;
+}
+
+function onDemandSpend(period: Record<string, unknown>): boolean {
+  if (!isObj(period.spendLimitUsage)) return false;
+  for (const key of ["individualUsed", "pooledUsed", "totalSpend", "overallUsed"]) {
+    const value = period.spendLimitUsage[key];
+    if (typeof value === "number" && Number.isFinite(value) && value > 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Map a GetPlanInfo body and a GetCurrentPeriodUsage body into one account
+ * observation. Null when the percent fields are missing or not 0–100, so a
+ * schema change sends nothing.
+ */
+export function mapCursorPeriodUsage(
+  plan: unknown,
+  period: unknown,
+  observedAt: number,
+): AgentAccountUsage | null {
+  if (!isObj(period) || !isObj(period.planUsage)) return null;
+  const total = percent(period.planUsage.totalPercentUsed);
+  const api = percent(period.planUsage.apiPercentUsed);
+  if (total === undefined || api === undefined) return null;
+
+  const planInfo = isObj(plan) && isObj(plan.planInfo) ? plan.planInfo : {};
+  const weekly = planInfo.includedUsagePeriod === WEEKLY_PERIOD;
+  const resetsAt = epochMs(planInfo.includedUsageResetsAt);
+  const window = (name: string, usedPercent: number) => ({
+    window: name,
+    ...(weekly ? { windowMinutes: WEEK_MINUTES } : {}),
+    usedPercent,
+    ...(resetsAt === undefined ? {} : { resetsAt }),
+  });
+  const windows = [window("included", total), window("api", api)];
+  const limited = windows.filter((item) => item.usedPercent >= CURSOR_PERIOD_LIMITED_PERCENT);
+  const status =
+    limited.length > 0
+      ? "limited"
+      : windows.some((item) => item.usedPercent >= CURSOR_PERIOD_WARNING_PERCENT)
+        ? "warning"
+        : "allowed";
+  const limitedResets = limited
+    .map((item) => item.resetsAt)
+    .filter((reset): reset is number => reset !== undefined);
+  const usage: AgentAccountUsage = {
+    status,
+    ...(limitedResets.length > 0 ? { resetsAt: Math.max(...limitedResets) } : {}),
+    ...(onDemandSpend(period) ? { usingOverage: true } : {}),
+    windows,
+    source: "cursor-period-usage",
+    observedAt,
+    coverage: { kind: "all-windows" },
+  };
+  return usage;
+}
+
+export async function readCursorAuthFromEnvironment(
+  environment: TaskEnvironmentAgentSessionSurface,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  if (signal?.aborted) return null;
+  let child: Awaited<ReturnType<TaskEnvironmentAgentSessionSurface["spawnSession"]>> | undefined;
+  const kill = (): void => {
+    if (!child) return;
+    void child.terminate("SIGKILL").catch(() => {});
+  };
+  signal?.addEventListener("abort", kill);
+  try {
+    child = await environment.spawnSession({
+      argv: ["cat", "--", CURSOR_AUTH_JSON],
+      user: "node",
+      projectEnvProfile: "task",
+      env: {},
+      maxOutputBytes: 32_768,
+    });
+    if (signal?.aborted) {
+      kill();
+      return null;
+    }
+    let text = "";
+    for await (const chunk of child.stdout) {
+      if (signal?.aborted) {
+        kill();
+        return null;
+      }
+      text += Buffer.from(chunk).toString("utf8");
+      if (text.length > 32_768) {
+        kill();
+        return null;
+      }
+    }
+    if (signal?.aborted) {
+      kill();
+      return null;
+    }
+    const exit = await child.completion;
+    return !signal?.aborted && exit.exitCode === 0 ? text : null;
+  } catch {
+    return null;
+  } finally {
+    signal?.removeEventListener("abort", kill);
+  }
+}
+
+async function postDashboard(
+  fetchImpl: typeof fetch,
+  token: string,
+  method: string,
+  signal: AbortSignal,
+): Promise<unknown | null> {
+  if (signal.aborted) return null;
+  try {
+    const response = await fetchImpl(
+      `${DASHBOARD_ORIGIN}/aiserver.v1.DashboardService/${method}`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          "Connect-Protocol-Version": "1",
+        },
+        body: "{}",
+        signal,
+      },
+    );
+    if (response.status !== 200) return null;
+    return (await response.json()) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read both dashboard methods and map them. Null on a non-200, a timeout, a
+ * bad body, or a shape we do not recognise. The token is sent only as the
+ * bearer for these two calls.
+ */
+export async function readCursorPeriodUsage(args: {
+  token: string;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  /** When set, this call does not start a second timer. The caller's deadline covers it. */
+  signal?: AbortSignal;
+  now?: number;
+}): Promise<AgentAccountUsage | null> {
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const owned = new AbortController();
+  const onParentAbort = (): void => owned.abort();
+  if (args.signal) {
+    if (args.signal.aborted) owned.abort();
+    else args.signal.addEventListener("abort", onParentAbort);
+  }
+  const timer =
+    args.signal === undefined
+      ? setTimeout(() => owned.abort(), args.timeoutMs ?? CURSOR_PERIOD_PROBE_TIMEOUT_MS)
+      : undefined;
+  try {
+    const [plan, period] = await Promise.all([
+      postDashboard(fetchImpl, args.token, "GetPlanInfo", owned.signal),
+      postDashboard(fetchImpl, args.token, "GetCurrentPeriodUsage", owned.signal),
+    ]);
+    if (owned.signal.aborted || plan === null || period === null) return null;
+    return mapCursorPeriodUsage(plan, period, args.now ?? Date.now());
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    args.signal?.removeEventListener("abort", onParentAbort);
+  }
+}