pi-provider-cursor-ask 0.1.0

package/src/extension/provider.ts

@@ -0,0 +1,277 @@
+/**
+ * Provider and OAuth registration for Cursor in Pi AI / Coding Agent.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
+import { registerApiProvider } from "@earendil-works/pi-ai/compat";
+import type { CursorParameterizedModel } from "../client/cursor-wire.js";
+import type { CursorModel } from "../stream/model-discovery.js";
+import { augmentCursorModels, FALLBACK_MODELS } from "../models/parameterized.js";
+import { buildAskCatalog } from "../models/ask-catalog.js";
+import {
+  buildNoReasoningEffortLookup,
+  buildRawModelLookup,
+  modelConfig,
+  processModels,
+  type CursorModelRouting,
+  type ProcessedModel,
+} from "../models/processing.js";
+import {
+  createCursorNativeStream,
+  discoverCursorCatalog,
+  readCachedCatalog,
+  type CursorCatalog,
+} from "../stream/native-core.js";
+import { getCursorAgentUrl } from "../stream/config.js";
+import {
+  generateCursorAuthParams,
+  getTokenExpiry,
+  pollCursorAuth,
+  refreshCursorToken,
+} from "../auth/oauth.js";
+import { setLastAvailableModels, setLastTokenSource } from "../diagnostics/diagnostics.js";
+import { debugExtensionLog } from "./debug-hooks.js";
+import { getStartupCursorAccessToken } from "./auth.js";
+import { CURSOR_ASK_IDENTITY } from "../identity.js";
+import { ProviderConstant, CredentialSource } from "../types/enums.js";
+
+export const STARTUP_CATALOG_FRESH_MS = 6 * 60 * 60 * 1000;
+export const BACKGROUND_CATALOG_REFRESH_TIMEOUT_MS = 20_000;
+
+export interface ProviderRegistrationContext {
+  getAccessToken: (options?: { forceRefresh?: boolean }) => Promise<string>;
+  setCurrentToken: (token: string, source: CredentialSource) => void;
+  onRegisteredModelsUpdated: (models: ProcessedModel[]) => void;
+}
+
+export function loadStartupCatalog(): CursorCatalog {
+  if (!process.env.PI_OFFLINE) {
+    const cached = readCachedCatalog();
+    if (cached) {
+      debugExtensionLog("model_discovery.startup.cached", {
+        rawCount: cached.rawModels.length,
+        parameterizedCount: cached.parameterizedModels.length,
+        ageMs: Date.now() - cached.savedAt,
+      });
+      return {
+        rawModels: cached.rawModels.length > 0 ? cached.rawModels : FALLBACK_MODELS,
+        parameterizedModels: cached.parameterizedModels,
+      };
+    }
+  }
+  return { rawModels: FALLBACK_MODELS, parameterizedModels: [] };
+}
+
+export async function refreshCatalogFromNetwork(
+  onTokenDiscovered?: (token: string, source: CredentialSource) => void,
+  options?: { signal?: AbortSignal },
+): Promise<CursorCatalog | undefined> {
+  if (process.env.PI_OFFLINE) return undefined;
+
+  let token: { accessToken: string; source: CredentialSource } | undefined;
+  try {
+    token = await getStartupCursorAccessToken();
+  } catch (err) {
+    debugExtensionLog("model_discovery.refresh.token_failed", {
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  if (!token) {
+    debugExtensionLog("model_discovery.refresh.skipped", { reason: "no_cursor_oauth_token" });
+    return undefined;
+  }
+
+  onTokenDiscovered?.(token.accessToken, token.source);
+  setLastTokenSource(token.source);
+
+  try {
+    const catalog = await discoverCursorCatalog(token.accessToken, { signal: options?.signal });
+    debugExtensionLog("model_discovery.refresh", {
+      tokenSource: token.source,
+      discoveredCount: catalog.rawModels.length,
+      parameterizedCount: catalog.parameterizedModels.length,
+    });
+    if (catalog.rawModels.length === 0 && catalog.parameterizedModels.length === 0) {
+      return undefined;
+    }
+    return {
+      rawModels: catalog.rawModels.length > 0 ? catalog.rawModels : FALLBACK_MODELS,
+      parameterizedModels: catalog.parameterizedModels,
+    };
+  } catch (err) {
+    debugExtensionLog("model_discovery.refresh.failed", {
+      tokenSource: token.source,
+      message: err instanceof Error ? err.message : String(err),
+    });
+    return undefined;
+  }
+}
+
+export interface ProviderManager {
+  registerModels: (
+    rawModels: CursorModel[],
+    parameterizedModels?: CursorParameterizedModel[],
+  ) => ProcessedModel[];
+  getLastRegisteredModels: () => ProcessedModel[];
+}
+
+export function createProviderManager(
+  pi: ExtensionAPI,
+  context: ProviderRegistrationContext,
+): ProviderManager {
+  let noReasoningEffortByModelId = new Map<string, string>();
+  let rawModelByEffortByModelId = new Map<string, Record<string, CursorModelRouting>>();
+  let lastRegisteredModels: ProcessedModel[] = [];
+  let catalogRefreshInFlight: Promise<void> | undefined;
+
+  const skipDedup = Boolean(process.env.PI_CURSOR_RAW_MODELS);
+
+  function applyModels(
+    rawModels: CursorModel[],
+    parameterizedModels: CursorParameterizedModel[] = [],
+  ): ProcessedModel[] {
+    const augmentedModels = augmentCursorModels(rawModels, parameterizedModels);
+    const processed = buildAskCatalog(
+      skipDedup
+        ? augmentedModels.map((m) => ({ ...m, supportsEffort: false }) as ProcessedModel)
+        : processModels(augmentedModels),
+    );
+    lastRegisteredModels = processed;
+    context.onRegisteredModelsUpdated(processed);
+    setLastAvailableModels(
+      processed
+        .map((m) => m.id)
+        .slice(0, 24)
+        .join(","),
+    );
+    noReasoningEffortByModelId = buildNoReasoningEffortLookup(processed);
+    rawModelByEffortByModelId = buildRawModelLookup(processed);
+    return processed;
+  }
+
+  function scheduleCatalogRefresh(): void {
+    if (catalogRefreshInFlight || process.env.PI_OFFLINE) return;
+    const signal = AbortSignal.timeout(BACKGROUND_CATALOG_REFRESH_TIMEOUT_MS);
+    catalogRefreshInFlight = refreshCatalogFromNetwork(context.setCurrentToken, { signal })
+      .then((catalog) => {
+        if (!catalog) return;
+        register(catalog.rawModels, catalog.parameterizedModels);
+      })
+      .catch((err) => {
+        debugExtensionLog("model_discovery.background.failed", {
+          message: err instanceof Error ? err.message : String(err),
+        });
+      })
+      .finally(() => {
+        catalogRefreshInFlight = undefined;
+      });
+  }
+
+  function register(
+    rawModels: CursorModel[],
+    parameterizedModels: CursorParameterizedModel[] = [],
+  ): ProcessedModel[] {
+    const processed = applyModels(rawModels, parameterizedModels);
+
+    const streamSimple = createCursorNativeStream({
+      getAccessToken: context.getAccessToken,
+      getNoReasoningEffortByModelId: () => noReasoningEffortByModelId,
+      getRawModelRoutingByModelId: () => rawModelByEffortByModelId,
+    });
+
+    registerApiProvider(
+      {
+        api: ProviderConstant.NativeApi,
+        stream: streamSimple,
+        streamSimple,
+      },
+      ProviderConstant.Source,
+    );
+
+    pi.registerProvider(ProviderConstant.ProviderId, {
+      baseUrl: getCursorAgentUrl(),
+      // Pi will not list models until apiKey or oauth resolves. Ask still reads
+      // CURSOR_ACCESS_TOKEN itself; this only satisfies Pi's auth gate (CI smoke).
+      apiKey: "$CURSOR_ACCESS_TOKEN",
+      api: ProviderConstant.NativeApi,
+      streamSimple,
+      models: processed.map(modelConfig),
+
+      async refreshModels(refreshContext: {
+        force?: boolean;
+        allowNetwork?: boolean;
+        signal?: AbortSignal;
+      }) {
+        if (!refreshContext.allowNetwork || refreshContext.signal?.aborted) {
+          return lastRegisteredModels.map(modelConfig);
+        }
+        if (!refreshContext.force) {
+          const cached = readCachedCatalog();
+          if (!cached || Date.now() - cached.savedAt > STARTUP_CATALOG_FRESH_MS) {
+            scheduleCatalogRefresh();
+          }
+          return lastRegisteredModels.map(modelConfig);
+        }
+        const catalog = await refreshCatalogFromNetwork(context.setCurrentToken, {
+          signal: refreshContext.signal,
+        });
+        if (!catalog) return lastRegisteredModels.map(modelConfig);
+        return applyModels(catalog.rawModels, catalog.parameterizedModels).map(modelConfig);
+      },
+
+      oauth: {
+        name: CURSOR_ASK_IDENTITY.displayName,
+
+        async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+          const { verifier, uuid, loginUrl } = await generateCursorAuthParams();
+          callbacks.onAuth({ url: loginUrl });
+          const { accessToken, refreshToken } = await pollCursorAuth(uuid, verifier);
+          context.setCurrentToken(accessToken, CredentialSource.PiOAuth);
+
+          const catalog = await discoverCursorCatalog(accessToken);
+          if (catalog.rawModels.length > 0 || catalog.parameterizedModels.length > 0) {
+            register(
+              catalog.rawModels.length > 0 ? catalog.rawModels : FALLBACK_MODELS,
+              catalog.parameterizedModels,
+            );
+          }
+
+          return {
+            refresh: refreshToken,
+            access: accessToken,
+            expires: getTokenExpiry(accessToken),
+          };
+        },
+
+        async refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+          const refreshed = await refreshCursorToken(credentials.refresh);
+          context.setCurrentToken(refreshed.access, CredentialSource.PiOAuthRefresh);
+
+          const catalog = await discoverCursorCatalog(refreshed.access);
+          if (catalog.rawModels.length > 0 || catalog.parameterizedModels.length > 0) {
+            register(
+              catalog.rawModels.length > 0 ? catalog.rawModels : FALLBACK_MODELS,
+              catalog.parameterizedModels,
+            );
+          }
+
+          return refreshed as OAuthCredentials;
+        },
+
+        getApiKey(credentials: OAuthCredentials): string {
+          context.setCurrentToken(credentials.access, CredentialSource.PiOAuth);
+          return ProviderConstant.NativeApi;
+        },
+      },
+    });
+
+    return processed;
+  }
+
+  return {
+    registerModels: register,
+    getLastRegisteredModels: () => lastRegisteredModels,
+  };
+}

package/src/extension/quota-adapter.ts

@@ -0,0 +1,175 @@
+/**
+ * Optional pi-meter guest quota sources.
+ *
+ * Cursor has two included pools. Composer uses Auto; Claude and other
+ * third-party rows use API. Registration uses the process-global mailbox so
+ * this package does not import pi-meter.
+ */
+
+import { CURSOR_ASK_IDENTITY } from "../identity.js";
+import { redactSecrets } from "../utils/security.js";
+import { getCursorUsageSummary, type CursorUsageSummary } from "../usage.js";
+
+export const CURSOR_QUOTA_ADAPTERS_KEY = Symbol.for("@zhcsyncer/pi-meter/quota-adapters");
+
+export type CursorQuotaPool = "auto" | "api";
+
+export const CURSOR_QUOTA_AUTO_ID = "cursor-auto";
+export const CURSOR_QUOTA_API_ID = "cursor-api";
+
+export interface CursorQuotaModelRef {
+  provider?: string;
+  id?: string;
+}
+
+export interface CursorQuotaWindow {
+  id: string;
+  label: string;
+  usedPercent: number;
+  resetsAt?: string;
+  note?: string;
+}
+
+export interface CursorQuotaSnapshot {
+  provider: string;
+  title: string;
+  primary?: CursorQuotaWindow;
+  windows: CursorQuotaWindow[];
+  fetchedAt: number;
+  ok: boolean;
+  error?: string;
+}
+
+export interface CursorQuotaAdapter {
+  id: string;
+  title: string;
+  matchProvider(model: CursorQuotaModelRef): boolean;
+  fetch(ctx: { modelRegistry?: unknown }, fetchedAt?: number): Promise<CursorQuotaSnapshot>;
+}
+
+interface QuotaAdapterHost {
+  register?(adapter: CursorQuotaAdapter): void;
+  list?(): unknown[];
+  mailbox?: unknown[];
+}
+
+const POOL_META: Record<
+  CursorQuotaPool,
+  { id: string; title: string; windowId: string; label: string }
+> = {
+  auto: { id: CURSOR_QUOTA_AUTO_ID, title: "Cursor Auto", windowId: "auto", label: "Auto" },
+  api: { id: CURSOR_QUOTA_API_ID, title: "Cursor API", windowId: "api", label: "API" },
+};
+
+function clampPercent(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(100, value));
+}
+
+export function isCursorComposerModelId(id: string | undefined): boolean {
+  return typeof id === "string" && /composer/i.test(id);
+}
+
+function poolPercent(summary: CursorUsageSummary, pool: CursorQuotaPool): number {
+  if (summary.isUnlimited) return 0;
+  const plan = summary.individualUsage?.plan;
+  const value = pool === "auto" ? plan?.autoPercentUsed : plan?.apiPercentUsed;
+  return clampPercent(value ?? 0);
+}
+
+export function cursorUsageToQuotaSnapshot(
+  summary: CursorUsageSummary,
+  fetchedAt: number,
+  pool: CursorQuotaPool,
+): CursorQuotaSnapshot {
+  const meta = POOL_META[pool];
+  const window: CursorQuotaWindow = {
+    id: meta.windowId,
+    label: meta.label,
+    usedPercent: poolPercent(summary, pool),
+    ...(summary.billingCycleEnd ? { resetsAt: summary.billingCycleEnd } : {}),
+    ...(summary.isUnlimited ? { note: "unlimited" } : {}),
+  };
+  return {
+    provider: meta.id,
+    title: meta.title,
+    primary: window,
+    windows: [window],
+    fetchedAt,
+    ok: true,
+  };
+}
+
+function failedSnapshot(
+  pool: CursorQuotaPool,
+  fetchedAt: number,
+  error: unknown,
+): CursorQuotaSnapshot {
+  const meta = POOL_META[pool];
+  return {
+    provider: meta.id,
+    title: meta.title,
+    windows: [],
+    fetchedAt,
+    ok: false,
+    error: redactSecrets(error instanceof Error ? error.message : String(error)),
+  };
+}
+
+export function createCursorQuotaAdapters(
+  getAccessToken: () => Promise<string>,
+): CursorQuotaAdapter[] {
+  const fetchPool = async (
+    pool: CursorQuotaPool,
+    fetchedAt: number,
+  ): Promise<CursorQuotaSnapshot> => {
+    try {
+      return cursorUsageToQuotaSnapshot(
+        await getCursorUsageSummary(getAccessToken),
+        fetchedAt,
+        pool,
+      );
+    } catch (error) {
+      return failedSnapshot(pool, fetchedAt, error);
+    }
+  };
+
+  return [
+    {
+      id: CURSOR_QUOTA_AUTO_ID,
+      title: POOL_META.auto.title,
+      matchProvider: (model) =>
+        model.provider === CURSOR_ASK_IDENTITY.providerId && isCursorComposerModelId(model.id),
+      fetch: async (_ctx, fetchedAt = Date.now()) => fetchPool("auto", fetchedAt),
+    },
+    {
+      id: CURSOR_QUOTA_API_ID,
+      title: POOL_META.api.title,
+      matchProvider: (model) =>
+        model.provider === CURSOR_ASK_IDENTITY.providerId && !isCursorComposerModelId(model.id),
+      fetch: async (_ctx, fetchedAt = Date.now()) => fetchPool("api", fetchedAt),
+    },
+  ];
+}
+
+export function registerCursorQuotaAdapter(adapter: CursorQuotaAdapter): void {
+  const host = (globalThis as Record<symbol, QuotaAdapterHost | undefined>)[
+    CURSOR_QUOTA_ADAPTERS_KEY
+  ];
+  if (typeof host?.register === "function") {
+    host.register(adapter);
+    return;
+  }
+  const mailbox = Array.isArray(host?.mailbox) ? host.mailbox : [];
+  mailbox.push(adapter);
+  (globalThis as Record<symbol, QuotaAdapterHost>)[CURSOR_QUOTA_ADAPTERS_KEY] = {
+    ...host,
+    mailbox,
+  };
+}
+
+export function registerCursorQuotaAdapters(getAccessToken: () => Promise<string>): void {
+  for (const adapter of createCursorQuotaAdapters(getAccessToken)) {
+    registerCursorQuotaAdapter(adapter);
+  }
+}

package/src/extension/report-dashboard.ts

@@ -0,0 +1,133 @@
+/**
+ * Editor-slot dashboard for Cursor command reports.
+ *
+ * Reports replace the bottom editor, the same place pi-meter uses, instead of
+ * writing into the chat transcript or floating over the conversation.
+ */
+
+import { Key, matchesKey, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export interface ReportDashboardTheme {
+  fg: (color: string, text: string) => string;
+  bold: (text: string) => string;
+}
+
+export type ReportTone = "info" | "error";
+
+export function reportViewportRows(terminalRows: number): number {
+  return Math.max(8, Math.min(24, Math.floor(Math.max(1, terminalRows) * 0.8) - 4));
+}
+
+export class CursorReportDashboard {
+  private scroll = 0;
+  private cachedWidth = -1;
+  private cachedLines: string[] = [];
+
+  constructor(
+    private readonly title: string,
+    private readonly body: string,
+    private readonly theme: ReportDashboardTheme,
+    private readonly tone: ReportTone = "info",
+    private readonly bodyRows = 16,
+  ) {}
+
+  public onDone?: () => void;
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape) || data === "q" || data === "Q") {
+      this.onDone?.();
+      return;
+    }
+    if (matchesKey(data, Key.down) || data === "j") {
+      this.scroll += 1;
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.up) || data === "k") {
+      this.scroll = Math.max(0, this.scroll - 1);
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.pageDown)) {
+      this.scroll += this.bodyRows;
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.pageUp)) {
+      this.scroll = Math.max(0, this.scroll - this.bodyRows);
+      this.invalidate();
+    }
+  }
+
+  invalidate(): void {
+    this.cachedWidth = -1;
+    this.cachedLines = [];
+  }
+
+  render(width: number): string[] {
+    if (this.cachedWidth === width && this.cachedLines.length > 0) return this.cachedLines;
+    const safeWidth = Math.max(1, width);
+    const t = this.theme;
+    const bodyColor = this.tone === "error" ? "error" : "text";
+    const wrapped = this.body
+      .split("\n")
+      .flatMap((line) => (line ? wrapTextWithAnsi(t.fg(bodyColor, line), safeWidth) : [""]));
+    const maxScroll = Math.max(0, wrapped.length - this.bodyRows);
+    this.scroll = Math.min(this.scroll, maxScroll);
+    const visible = wrapped.slice(this.scroll, this.scroll + this.bodyRows);
+    const footer =
+      wrapped.length > this.bodyRows
+        ? `[↑↓] scroll ${this.scroll + 1}-${this.scroll + visible.length}/${wrapped.length}  [q] close`
+        : "[q] close";
+    const lines = [
+      ...wrapTextWithAnsi(t.fg("accent", t.bold(this.title)), safeWidth),
+      "",
+      ...visible,
+      "",
+      ...wrapTextWithAnsi(t.fg("dim", footer), safeWidth),
+    ];
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+    return lines;
+  }
+}
+
+export async function showCursorReport(
+  ctx: Pick<ExtensionCommandContext, "mode" | "hasUI" | "ui">,
+  title: string,
+  body: string,
+  tone: ReportTone = "info",
+): Promise<void> {
+  if (ctx.mode === "tui" && ctx.hasUI) {
+    await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+      const dash = new CursorReportDashboard(
+        title,
+        body,
+        {
+          fg: (color, text) => theme.fg(color as never, text),
+          bold: (text) => theme.bold(text),
+        },
+        tone,
+        reportViewportRows(tui.terminal.rows),
+      );
+      dash.onDone = () => done();
+      return {
+        render: (width) => dash.render(width),
+        invalidate: () => dash.invalidate(),
+        handleInput: (data) => {
+          dash.handleInput(data);
+          tui.requestRender();
+        },
+      };
+    });
+    return;
+  }
+
+  if (ctx.hasUI) {
+    ctx.ui.notify(body, tone === "error" ? "error" : "info");
+    return;
+  }
+  if (tone === "error") console.error(body);
+  else console.log(body);
+}

package/src/identity.ts

@@ -0,0 +1,16 @@
+/**
+ * Fork identity kept in one place so upstream syncs do not scatter provider
+ * naming changes across the transport implementation.
+ */
+export const CURSOR_ASK_IDENTITY = {
+  packageName: "pi-provider-cursor-ask",
+  providerId: "cursor",
+  nativeApi: "cursor-native",
+  apiSource: "pi-provider-cursor-ask",
+  displayName: "Cursor Ask",
+  commandName: "cursor",
+} as const;
+
+export const CURSOR_ASK_LOGIN_COMMAND = `/login ${CURSOR_ASK_IDENTITY.providerId}`;
+export const CURSOR_ASK_COMMAND = `/${CURSOR_ASK_IDENTITY.commandName}`;
+export const CURSOR_ASK_DOCTOR_COMMAND = `${CURSOR_ASK_COMMAND} doctor`;