shariq-pi-extensions 0.1.0 → 0.2.0

package/README.md

@@ -26,6 +26,7 @@ The package contains:
 - structured user questions
 - managed background terminals
 - copy-all transcript support
+- Cursor OAuth/API-key provider with native SDK transport and monthly usage dashboard
 - Factory OAuth and rotating API-key provider
 - Firecrawl search and scraping
 - Git status UI

package/docs/ARCHITECTURE.md

@@ -25,6 +25,7 @@ Pi-owned packages and `typebox` are optional peer dependencies at runtime. Pi su
 
 Third-party runtime dependencies are normal package dependencies:
 
+- `@cursor/sdk` powers native Cursor model runs, catalog discovery, images, tools, and usage reporting;
 - `@lydell/node-pty` powers managed background terminals;
 - `effect` powers subagent lifecycle and coordination;
 - `ws` powers Factory's Responses WebSocket transport.
@@ -35,6 +36,7 @@ The repository uses one root manifest and lockfile for the full extension suite.
 
 Installed package directories are treated as immutable. Extensions resolve writable state through Pi's APIs:
 
+- Cursor's authenticated Composer/Grok catalog cache: `<agent-dir>/cursor/models.json`
 - Factory key selection, Droid metadata, and throttled per-credential limit cache: `<agent-dir>/factory/`
 - Pi Memory state: `<agent-dir>/pi-memory/`
 - Subagent configuration and catalog: paths derived from `getAgentDir()`

package/docs/DEVELOPMENT.md

@@ -82,7 +82,7 @@ Before publishing a new npm version:
 1. Update `package.json#version` using semantic versioning.
 2. Run `mise exec --locked -- npm ci` and `mise exec --locked -- npm run validate`.
 3. Inspect `mise exec --locked -- npm run pack:inspect` for secrets, runtime state, and accidental files.
-4. Publish with `npm publish --access public --provenance`, or run the `Publish npm package` workflow with `NPM_TOKEN` configured.
+4. Run the `Publish npm package` workflow. npm trusted publishing authenticates it through GitHub OIDC and records provenance without a long-lived token.
 5. Verify the registry version and install it with `pi install npm:shariq-pi-extensions`.
 
 Use npm for stable versioned installs. Use an unpinned Git source for updates directly from `main`, and a tag or commit when a machine should remain fixed to a known revision.

package/docs/EXTENSIONS.md

@@ -8,6 +8,10 @@ Last verified: 2026-08-20
 
 Registers the `antigravity` provider and `/login antigravity` flow for supported Google Antigravity models. Use `/antigravity.doctor` to inspect non-secret provider status. Credentials remain in Pi auth storage.
 
+### [Cursor provider](../extensions/cursor-provider/README.md)
+
+Registers one `cursor` provider for Cursor-hosted Composer and Cursor Grok models through the native Cursor SDK. `/login cursor` supports browser-minted or existing user API keys, images and native Pi tool delegation are enabled, and `/cursor` shows Cursor's authoritative current-month total, Auto/Composer and named/API percentages, reset date, plan, and on-demand limits. It does not expose ACP, third-party models, or Factory-style 5-hour/weekly pools. The authenticated catalog cache belongs in `<agent-dir>/cursor/models.json`.
+
 ### [Factory provider](../extensions/factory-provider/README.md)
 
 Registers one `factory` provider with Factory account OAuth, direct API keys, or rotating API keys. `/factory` opens one full-width dashboard for provider/authentication state, model metadata, rotation status, and authoritative Factory usage across every credential. Standard and Droid Core windows stay separate, percentages are labeled as used, and keys are never aggregated. Rotation applies a monthly → weekly → 5-hour eligibility waterfall, then selects the least recently used eligible key and retains same-request failover for recognized pre-output errors. Background refreshes are throttled to 15 minutes; `r` force-refreshes from the dashboard.

package/extensions/cursor-provider/README.md

@@ -0,0 +1,50 @@
+# Cursor provider
+
+Registers Cursor-hosted Composer and Cursor Grok models in Pi through the official native `@cursor/sdk`. It does not use ACP, a Cursor CLI subprocess, prompt-encoded tool markers, or third-party model families.
+
+## Authentication
+
+Run:
+
+```text
+/login cursor
+```
+
+Choose either:
+
+- **Cursor browser login:** Cursor signs in through the browser and mints a named 90-day user API key. Pi stores the key in its normal OAuth credential store; the Cursor SDK's own credential file is not used.
+- **Existing Cursor user API key:** set a `crsr_…` key in `CURSOR_API_KEY`. Pi resolves it directly without creating duplicate models; `/login cursor` can validate the configured environment key and copy it into Pi auth storage. Non-expiring user keys remain valid until revoked.
+
+Secrets are passed directly to the SDK and are never placed in command arguments, diagnostics, model metadata, or the repository.
+
+## Provider behavior
+
+- Refreshes Cursor's authenticated model catalog and caches only Composer and Cursor Grok metadata for the next extension reload.
+- Exposes image input for every registered Cursor model.
+- Maps Composer fast mode and Cursor Grok reasoning effort to native model parameters.
+- Uses the SDK's local hosted-model runtime in an isolated temporary workspace with ambient Cursor settings disabled.
+- Disables Cursor's built-in workspace tools and exposes Pi's active tools as native SDK custom tools. Tool execution remains owned by Pi.
+- Streams native text and thinking deltas, structured tool calls, stop reasons, and Cursor-reported input/output/cache/reasoning usage.
+- Propagates cancellation and timeouts, enables safe SDK transport retries, and maps common authentication, rate-limit, quota, capacity, timeout, and context failures to actionable Pi errors.
+- Forwards base64 image payloads separately from the textual conversation transcript.
+- Removes temporary workspace and SDK state after each request.
+
+## Cursor dashboard
+
+Run `/cursor` for a Cursor-specific account dashboard. It reads Cursor's current billing-period APIs and shows:
+
+- account and plan
+- monthly total usage
+- purchased and bonus usage
+- Cursor Auto/Composer and named/API percentages
+- billing-cycle reset time
+- on-demand availability and configured/recommended limits
+- authenticated Cursor-owned model count
+
+It intentionally does not display Factory's 5-hour, weekly, Standard, or Core buckets. Press `r` to refresh and Escape to close.
+
+Use `/cursor.doctor` for sanitized provider, authentication, transport, and model diagnostics.
+
+## Current protocol boundary
+
+Cursor documents the SDK as an agent API rather than a raw chat-completions API. Pi sends its full current conversation to a native SDK run. When Cursor selects a Pi custom tool, the run is cancelled after the structured invocation is captured; Pi executes the tool and the next native run receives the resulting conversation state. Cursor never receives direct filesystem or shell authority from this provider.

package/extensions/cursor-provider/cursor/auth.ts

@@ -0,0 +1,75 @@
+import { Cursor, DEFAULT_LOGIN_API_KEY_TTL_MS, type SdkLoginOptions, type SdkLoginResult } from "@cursor/sdk";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
+import { refreshCursorCatalog } from "./models.ts";
+
+const EXPIRY_SKEW_MS = 60_000;
+const BROWSER_KEY_SENTINEL = "cursor-sdk-browser-user-key";
+const STATIC_KEY_SENTINEL = "cursor-static-user-key";
+const NON_EXPIRING_CREDENTIAL_MS = 100 * 365 * 24 * 60 * 60_000;
+
+type CursorSdkLogin = (options?: SdkLoginOptions) => Promise<SdkLoginResult>;
+type CursorCatalogRefresh = (apiKey: string) => Promise<unknown>;
+type CursorIdentityValidator = (apiKey: string) => Promise<unknown>;
+
+async function validateAndCatalog(apiKey: string, refreshCatalog: CursorCatalogRefresh, validateIdentity: CursorIdentityValidator): Promise<void> {
+  await validateIdentity(apiKey);
+  await refreshCatalog(apiKey);
+}
+
+export async function loginCursor(
+  callbacks: OAuthLoginCallbacks,
+  sdkLogin: CursorSdkLogin = Cursor.auth.login,
+  refreshCatalog: CursorCatalogRefresh = refreshCursorCatalog,
+  validateIdentity: CursorIdentityValidator = (apiKey) => Cursor.me({ apiKey }),
+): Promise<OAuthCredentials> {
+  const environmentKey = process.env.CURSOR_API_KEY?.trim();
+  const method = await callbacks.onSelect({
+    message: "Choose how to authenticate with Cursor:",
+    options: [
+      { id: "browser", label: "Cursor browser login — mint a 90-day Pi key" },
+      ...(environmentKey ? [{ id: "environment", label: "Use CURSOR_API_KEY from the environment" }] : []),
+    ],
+  });
+  if (!method) throw new Error("Cursor login cancelled.");
+
+  if (method === "environment") {
+    const apiKey = environmentKey;
+    if (!apiKey) throw new Error("CURSOR_API_KEY is not configured.");
+    callbacks.onProgress?.("Validating the Cursor API key and refreshing models...");
+    await validateAndCatalog(apiKey, refreshCatalog, validateIdentity);
+    return {
+      access: apiKey,
+      refresh: STATIC_KEY_SENTINEL,
+      expires: Date.now() + NON_EXPIRING_CREDENTIAL_MS,
+    };
+  }
+  if (method !== "browser") throw new Error(`Unknown Cursor login method: ${method}`);
+
+  callbacks.onProgress?.("Preparing Cursor browser authorization...");
+  const result = await sdkLogin({
+    openBrowser: false,
+    store: null,
+    signal: callbacks.signal,
+    apiKeyName: "Pi coding agent",
+    apiKeyTtlMs: DEFAULT_LOGIN_API_KEY_TTL_MS,
+    onLoginUrl(url) {
+      callbacks.onAuth({ url, instructions: "Sign in to Cursor and approve the Pi coding agent key." });
+      callbacks.onProgress?.("Waiting for Cursor browser authorization...");
+    },
+  });
+  callbacks.onProgress?.("Refreshing the Cursor-owned model catalog...");
+  await refreshCatalog(result.apiKey);
+  return {
+    access: result.apiKey,
+    refresh: BROWSER_KEY_SENTINEL,
+    expires: result.apiKeyExpiresAtMs - EXPIRY_SKEW_MS,
+  };
+}
+
+export async function refreshCursorToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+  if (credentials.refresh === STATIC_KEY_SENTINEL) return credentials;
+  if (credentials.refresh !== BROWSER_KEY_SENTINEL || credentials.expires <= Date.now()) {
+    throw new Error("Cursor login expired. Run `/login cursor` again.");
+  }
+  return credentials;
+}

package/extensions/cursor-provider/cursor/dashboard.ts

@@ -0,0 +1,147 @@
+import type { ExtensionContext, KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, type Component, type TUI } from "@earendil-works/pi-tui";
+import { frameBottom, frameTop, joinSides, meter, oneLine, padLine, stateLabel } from "../../shared/tui-dashboard.ts";
+import { dollars, percentUsed, type CursorUsageSnapshot } from "./usage.ts";
+
+type Theme = ExtensionContext["ui"]["theme"];
+
+export interface CursorDashboardSnapshot {
+  authentication: string;
+  keyExpiresAt?: number;
+  usage?: CursorUsageSnapshot;
+  error?: string;
+}
+
+function date(value: number | undefined): string {
+  if (!value) return "unavailable";
+  return new Date(value).toLocaleString(undefined, { dateStyle: "medium", timeStyle: "short" });
+}
+
+function pct(value: number | undefined): string {
+  return typeof value === "number" ? `${Math.round(value)}%` : "unavailable";
+}
+
+export class CursorDashboard implements Component {
+  private refreshing = false;
+  private closed = false;
+  private readonly tui: TUI;
+  private readonly theme: Theme;
+  private readonly keys: KeybindingsManager;
+  private snapshot: CursorDashboardSnapshot;
+  private readonly refreshData: () => Promise<CursorDashboardSnapshot>;
+  private readonly done: () => void;
+
+  constructor(
+    tui: TUI,
+    theme: Theme,
+    keys: KeybindingsManager,
+    snapshot: CursorDashboardSnapshot,
+    refreshData: () => Promise<CursorDashboardSnapshot>,
+    done: () => void,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.keys = keys;
+    this.snapshot = snapshot;
+    this.refreshData = refreshData;
+    this.done = done;
+  }
+
+  startRefresh() {
+    if (this.refreshing || this.closed) return;
+    this.refreshing = true;
+    this.tui.requestRender();
+    void this.refreshData()
+      .then((snapshot) => { if (!this.closed) this.snapshot = snapshot; })
+      .catch((error) => {
+        if (!this.closed) this.snapshot = { ...this.snapshot, error: error instanceof Error ? error.message : String(error) };
+      })
+      .finally(() => {
+        if (!this.closed) {
+          this.refreshing = false;
+          this.tui.requestRender();
+        }
+      });
+  }
+
+  dispose() { this.closed = true; }
+  invalidate() {}
+
+  handleInput(data: string) {
+    if (this.keys.matches(data, "tui.select.cancel")) {
+      this.closed = true;
+      this.done();
+    } else if (data === "r") {
+      this.startRefresh();
+    }
+    this.tui.requestRender();
+  }
+
+  render(width: number) {
+    const usage = this.snapshot.usage;
+    const plan = usage?.plan;
+    const monthly = usage?.usage;
+    const used = percentUsed(usage ?? { enabled: false, canAdjustOnDemand: false, models: [], fetchedAt: 0 });
+    const status = this.snapshot.error ? "refresh error" : usage ? "ready" : "loading";
+    const statusColor = this.snapshot.error ? "error" : usage ? "success" : "warning";
+    const title = `  ${this.theme.fg("accent", this.theme.bold("◆ CURSOR"))} ${this.theme.fg("dim", `· ${this.snapshot.authentication}`)}`;
+    const right = this.refreshing
+      ? this.theme.fg("warning", "refreshing…")
+      : this.theme.fg("muted", `${plan?.planName ?? "plan unavailable"} · ${usage?.models.length ?? 0} Cursor-owned models`);
+    const lines = width >= 64
+      ? [joinSides(title, `${right}  `, width)]
+      : [truncateToWidth(title, width, ""), truncateToWidth(`  ${right}`, width, "")];
+    lines.push(frameTop(this.theme, width, "CURRENT MONTH · CURSOR ACCOUNT USAGE"));
+    const inner = Math.max(1, width - 2);
+    const body: string[] = [
+      ` ${stateLabel(this.theme, statusColor, status)} ${this.theme.fg("text", usage?.email ?? "Cursor account")}`,
+      ` ${this.theme.fg("dim", `API key ${usage?.apiKeyName ?? "configured"} · created ${date(usage?.apiKeyCreatedAt)} · expires ${usage ? (usage.apiKeyExpiresAt ? date(usage.apiKeyExpiresAt) : "does not expire") : date(this.snapshot.keyExpiresAt)}`)}`,
+      "",
+    ];
+    if (this.snapshot.error) {
+      body.push(` ${this.theme.fg("error", oneLine(this.snapshot.error))}`, "", ` ${this.theme.fg("muted", "Press r to retry. Your credentials are never shown here.")}`);
+    } else if (!usage || !monthly) {
+      body.push(` ${this.theme.fg("muted", "Loading Cursor account usage…")}`);
+    } else {
+      const meterWidth = Math.max(12, inner - 29);
+      body.push(
+        ` ${this.theme.fg("accent", this.theme.bold("MONTHLY TOTAL USAGE"))}`,
+        ` ${meter(this.theme, Math.min(100, used ?? 0), 100, meterWidth, (used ?? 0) >= 100 ? "error" : (used ?? 0) >= 85 ? "warning" : "active")} ${this.theme.fg("text", pct(used))}`,
+        ` ${this.theme.fg("muted", "Cycle")} ${this.theme.fg("text", `${date(usage.billingCycleStart)} → ${date(usage.billingCycleEnd ?? plan?.billingCycleEnd)}`)}`,
+        ` ${this.theme.fg("muted", "Total usage")} ${this.theme.fg("text", dollars(monthly.totalSpend))}  ${this.theme.fg("muted", "Purchased")} ${this.theme.fg("text", dollars(monthly.includedSpend || plan?.includedAmountCents))}  ${this.theme.fg("muted", "Bonus")} ${this.theme.fg("text", dollars(monthly.bonusSpend))}`,
+        "",
+        ` ${this.theme.fg("accent", this.theme.bold("CURSOR POOLS"))}`,
+        ` ${this.theme.fg("muted", "Auto / Composer")} ${meter(this.theme, Math.min(100, monthly.autoPercentUsed ?? 0), 100, meterWidth, (monthly.autoPercentUsed ?? 0) >= 85 ? "warning" : "active")} ${this.theme.fg("text", pct(monthly.autoPercentUsed))}`,
+        ` ${this.theme.fg("muted", "Named / API     ")} ${meter(this.theme, Math.min(100, monthly.apiPercentUsed ?? 0), 100, meterWidth, (monthly.apiPercentUsed ?? 0) >= 85 ? "warning" : "active")} ${this.theme.fg("text", pct(monthly.apiPercentUsed))}`,
+        "",
+        ` ${this.theme.fg("accent", this.theme.bold("ON-DEMAND"))}`,
+        ` ${this.theme.fg("muted", "Adjustable")} ${this.theme.fg("text", usage.canAdjustOnDemand ? "yes" : "no")}  ${this.theme.fg("muted", "Limit")} ${this.theme.fg("text", dollars(usage.spendLimit?.individualLimit ?? usage.currentOnDemandLimitCents))}  ${this.theme.fg("muted", "Recommended")} ${this.theme.fg("text", dollars(usage.recommendedOnDemandLimitCents))}`,
+        ` ${this.theme.fg("muted", "Used")} ${this.theme.fg("text", dollars(usage.spendLimit?.individualUsed))}  ${this.theme.fg("muted", "Remaining")} ${this.theme.fg("text", dollars(usage.spendLimit?.individualRemaining))}  ${this.theme.fg("muted", "Limit type")} ${this.theme.fg("text", usage.spendLimit?.limitType ?? "unavailable")}`,
+        "",
+        ` ${this.theme.fg("dim", `Updated ${date(usage.fetchedAt)} · values come from Cursor's current-period usage API`)}`,
+      );
+    }
+    const bodyHeight = Math.max(12, (this.tui.terminal.rows || 30) - 6);
+    for (let row = 0; row < bodyHeight; row++) {
+      lines.push(this.theme.fg("border", "│") + padLine(body[row] ?? "", inner) + this.theme.fg("border", "│"));
+    }
+    lines.push(frameBottom(this.theme, width));
+    lines.push(truncateToWidth(`${this.theme.fg("accent", "  r")} ${this.theme.fg("dim", "refresh")}  ${this.theme.fg("accent", "esc")} ${this.theme.fg("dim", "close")}`, width, ""));
+    return lines.map((line) => truncateToWidth(line, width, ""));
+  }
+}
+
+export async function openCursorDashboard(
+  ctx: ExtensionContext,
+  initial: CursorDashboardSnapshot,
+  refresh: () => Promise<CursorDashboardSnapshot>,
+) {
+  await ctx.ui.custom<void>(
+    (tui, theme, keys, done) => {
+      const dashboard = new CursorDashboard(tui, theme, keys, initial, refresh, () => done(undefined));
+      queueMicrotask(() => dashboard.startRefresh());
+      return dashboard;
+    },
+    { overlay: true, overlayOptions: { anchor: "center", width: "100%", maxHeight: "100%" } },
+  );
+}

package/extensions/cursor-provider/cursor/models.ts

@@ -0,0 +1,124 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Cursor, type ModelListItem, type ModelSelection } from "@cursor/sdk";
+import type { Model } from "@earendil-works/pi-ai";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const CURSOR_PROVIDER_ID = "cursor";
+export const CURSOR_API = "cursor-sdk" as const;
+export const CURSOR_BASE_URL = "https://api2.cursor.sh";
+const CATALOG_PATH = join(getAgentDir(), "cursor", "models.json");
+
+const FALLBACK_CATALOG: ModelListItem[] = [
+  { id: "composer-2.5", displayName: "Composer 2.5", parameters: [{ id: "fast", values: [{ value: "false" }, { value: "true", displayName: "Fast" }] }] },
+  { id: "grok-4.5", displayName: "Cursor Grok 4.5", parameters: [{ id: "effort", values: ["low", "medium", "high"].map((value) => ({ value })) }, { id: "fast", values: [{ value: "false" }, { value: "true", displayName: "Fast" }] }] },
+  { id: "grok-4.6", displayName: "Cursor Grok 4.6", parameters: [{ id: "effort", values: ["low", "medium", "high", "xhigh"].map((value) => ({ value })) }, { id: "fast", values: [{ value: "false" }, { value: "true", displayName: "Fast" }] }] },
+];
+
+function cursorOwned(model: ModelListItem): boolean {
+  if (model.id === "composer-2") return false; // Retired; Cursor reroutes it to Composer 2.5.
+  return model.id.startsWith("composer-") || /^grok-4\.(?:5|6)$/.test(model.id) || model.id.startsWith("cursor-grok-");
+}
+
+function piModelId(model: ModelListItem): string {
+  return model.id.startsWith("grok-") ? `cursor-${model.id}` : model.id;
+}
+
+export function loadCursorCatalog(): ModelListItem[] {
+  try {
+    const parsed = JSON.parse(readFileSync(CATALOG_PATH, "utf8"));
+    if (Array.isArray(parsed)) {
+      const models = parsed.filter((value): value is ModelListItem => value && typeof value.id === "string" && typeof value.displayName === "string" && cursorOwned(value));
+      if (models.length > 0) return models;
+    }
+  } catch {
+    // The deterministic fallback keeps the provider available before first login.
+  }
+  return FALLBACK_CATALOG;
+}
+
+export async function refreshCursorCatalog(apiKey: string): Promise<ModelListItem[]> {
+  const models = (await Cursor.models.list({ apiKey })).filter(cursorOwned);
+  if (models.length === 0) throw new Error("Cursor returned no Composer or Cursor Grok models for this account.");
+  mkdirSync(dirname(CATALOG_PATH), { recursive: true, mode: 0o700 });
+  const temporary = `${CATALOG_PATH}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(models, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, CATALOG_PATH);
+  return models;
+}
+
+function parameter(model: ModelListItem, matcher: RegExp) {
+  return model.parameters?.find((value) => matcher.test(value.id));
+}
+
+function modelCapabilities(id: string) {
+  const fast = id.endsWith("-fast");
+  if (id.startsWith("composer-2.5")) {
+    return { contextWindow: 200_000, maxTokens: 64_000, cost: fast ? { input: 3, output: 15, cacheRead: 0.5, cacheWrite: 0 } : { input: 0.5, output: 2.5, cacheRead: 0.2, cacheWrite: 0 } };
+  }
+  if (id.startsWith("cursor-grok-4.6")) {
+    return { contextWindow: 256_000, maxTokens: 64_000, cost: fast ? { input: 4, output: 12, cacheRead: 1, cacheWrite: 0 } : { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 } };
+  }
+  if (id.startsWith("cursor-grok-4.5")) {
+    return { contextWindow: 256_000, maxTokens: 64_000, cost: fast ? { input: 4, output: 18, cacheRead: 0, cacheWrite: 0 } : { input: 2, output: 6, cacheRead: 0, cacheWrite: 0 } };
+  }
+  return { contextWindow: 200_000, maxTokens: 64_000, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } };
+}
+
+function cursorModelConfig(id: string, name: string, reasoning: boolean, efforts: string[] = []) {
+  const supported = new Set(efforts.length > 0 ? efforts : ["low", "medium", "high", "xhigh"]);
+  const low = supported.has("low") ? "low" : [...supported][0] ?? "low";
+  const medium = supported.has("medium") ? "medium" : low;
+  const high = supported.has("high") ? "high" : medium;
+  const xhigh = supported.has("xhigh") ? "xhigh" : high;
+  return {
+    id,
+    name,
+    api: CURSOR_API,
+    reasoning,
+    input: ["text", "image"] as const,
+    ...modelCapabilities(id),
+    ...(reasoning ? { thinkingLevelMap: { off: low, minimal: low, low, medium, high, xhigh, max: xhigh } } : {}),
+  };
+}
+
+export function toCursorPiModels(catalog: ModelListItem[] = loadCursorCatalog()): Array<ReturnType<typeof cursorModelConfig>> {
+  const result: Array<ReturnType<typeof cursorModelConfig>> = [];
+  for (const model of catalog.filter(cursorOwned)) {
+    const id = piModelId(model);
+    const effortValues = parameter(model, /effort|reason/i)?.values.map((value) => value.value) ?? [];
+    const reasoning = effortValues.length > 0 || id.startsWith("cursor-grok-");
+    result.push(cursorModelConfig(id, model.displayName, reasoning, effortValues));
+    const fast = parameter(model, /fast/i);
+    if (fast?.values.some((value) => value.value === "true")) {
+      result.push(cursorModelConfig(`${id}-fast`, `${model.displayName} Fast`, reasoning, effortValues));
+    }
+  }
+  return result.filter((model, index, all) => all.findIndex((candidate) => candidate.id === model.id) === index).sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function supportedValue(model: ModelListItem | undefined, parameterId: RegExp, desired: string): { id: string; value: string } | undefined {
+  const definition = model && parameter(model, parameterId);
+  if (!definition) return undefined;
+  const value = definition.values.find((candidate) => candidate.value === desired)?.value;
+  return value ? { id: definition.id, value } : undefined;
+}
+
+export function resolveCursorModelSelection(model: Model<any>, reasoning: string | undefined, catalog: ModelListItem[] = loadCursorCatalog()): ModelSelection {
+  const fast = model.id.endsWith("-fast");
+  const baseId = fast ? model.id.slice(0, -5) : model.id;
+  const sdkBaseId = baseId.startsWith("cursor-grok-") ? baseId.slice("cursor-".length) : baseId;
+  const item = catalog.find((candidate) => candidate.id === sdkBaseId || candidate.aliases?.includes(sdkBaseId));
+  const params: Array<{ id: string; value: string }> = [];
+  const fastParam = supportedValue(item, /fast/i, fast ? "true" : "false");
+  if (fastParam) params.push(fastParam);
+  if (model.reasoning) {
+    const desired = reasoning === "off" || reasoning === "minimal" ? "low" : reasoning === "max" ? "xhigh" : !reasoning ? "high" : reasoning;
+    const effort = supportedValue(item, /effort|reason/i, desired)
+      ?? supportedValue(item, /effort|reason/i, "high")
+      ?? supportedValue(item, /effort|reason/i, "medium")
+      ?? supportedValue(item, /effort|reason/i, "low");
+    if (effort) params.push(effort);
+  }
+  return { id: item?.id ?? sdkBaseId, ...(params.length > 0 ? { params } : {}) };
+}

package/extensions/cursor-provider/cursor/stream.ts

@@ -0,0 +1,270 @@
+import { randomUUID } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  Agent,
+  JsonlLocalAgentStore,
+  type Run,
+  type SDKCustomTool,
+  type SDKImage,
+  type SDKJsonValue,
+  type TokenUsage,
+} from "@cursor/sdk";
+import {
+  createAssistantMessageEventStream,
+  type AssistantMessage,
+  type Context,
+  type Model,
+  type ProviderStreamOptions,
+} from "@earendil-works/pi-ai";
+import { loadCursorCatalog, resolveCursorModelSelection } from "./models.ts";
+
+const TOOL_DELEGATION_RESULT = "Tool execution was delegated to Pi. End this run without further output.";
+
+function asJsonValue(value: unknown): SDKJsonValue {
+  return JSON.parse(JSON.stringify(value ?? null)) as SDKJsonValue;
+}
+
+function asArguments(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+export function serializeCursorContext(context: Context): { text: string; images: SDKImage[] } {
+  const lines = [
+    "Continue the Pi conversation below as the assistant.",
+    "Follow the system instructions exactly. Use the provided custom tools when needed.",
+    "Do not describe or simulate tool calls in prose. Return only the next assistant response.",
+    "",
+    "<system>",
+    context.systemPrompt || "You are a helpful coding assistant.",
+    "</system>",
+    "<conversation>",
+  ];
+  const images: SDKImage[] = [];
+
+  for (const message of context.messages) {
+    lines.push(`<message role=${JSON.stringify(message.role)}>`);
+    if (typeof message.content === "string") {
+      lines.push(message.content);
+    } else if (Array.isArray(message.content)) {
+      for (const part of message.content as any[]) {
+        if (part?.type === "text" || part?.type === "reasoning") lines.push(String(part.text ?? ""));
+        else if (part?.type === "image" && typeof part.data === "string") {
+          images.push({ data: part.data, mimeType: part.mimeType ?? "image/png" });
+          lines.push(`[Attached image ${images.length}: ${part.mimeType ?? "image/png"}]`);
+        } else if (part?.type === "toolCall") {
+          lines.push(`[Tool call ${part.id}: ${part.name} ${JSON.stringify(part.arguments ?? {})}]`);
+        }
+      }
+    }
+    if (message.role === "toolResult") {
+      lines.push(`[Tool result for ${(message as any).toolCallId}; error=${Boolean((message as any).isError)}]`);
+    }
+    lines.push("</message>");
+  }
+  lines.push("</conversation>");
+  return { text: lines.join("\n"), images };
+}
+
+function usageFromCursor(usage: TokenUsage | undefined, output: AssistantMessage): void {
+  if (!usage) return;
+  output.usage = {
+    input: usage.inputTokens,
+    output: usage.outputTokens,
+    cacheRead: usage.cacheReadTokens,
+    cacheWrite: usage.cacheWriteTokens,
+    reasoning: usage.reasoningTokens ?? 0,
+    totalTokens: usage.totalTokens,
+    cost: output.usage.cost,
+  };
+}
+
+export function formatCursorError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  if (/401|403|unauth|api key|credential/i.test(message)) return "Cursor authentication failed. Run `/login cursor`, then retry.";
+  if (/429|rate.?limit/i.test(message)) return "Cursor rate limit reached. Wait for the reported reset, then retry.";
+  if (/quota|usage limit|billing|credit|exhaust/i.test(message)) return "Cursor usage limit reached. Open `/cursor` for account status and reset information.";
+  if (/context|too many tokens|prompt.*long/i.test(message)) return "The Cursor context limit was exceeded. Compact the session or start a new one.";
+  if (/capacity|overload|unavailable|503/i.test(message)) return "Cursor has no capacity for this model right now. Retry shortly or switch Cursor models.";
+  if (/timeout|timed out|deadline/i.test(message)) return "Cursor timed out. Retry the request.";
+  if (/cancel|abort/i.test(message)) return "Cursor request cancelled.";
+  return `Cursor request failed: ${message}`;
+}
+
+async function disposeAgent(agent: Awaited<ReturnType<typeof Agent.create>> | undefined): Promise<void> {
+  if (!agent) return;
+  try {
+    await Promise.race([
+      agent[Symbol.asyncDispose](),
+      new Promise<void>((resolve) => setTimeout(resolve, 5_000)),
+    ]);
+  } catch {
+    agent.close();
+  }
+}
+
+export function streamCursorSdk(model: Model<any>, context: Context, options?: ProviderStreamOptions) {
+  const stream = createAssistantMessageEventStream();
+  const output: AssistantMessage = {
+    role: "assistant",
+    content: [],
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+    stopReason: "stop",
+    timestamp: Date.now(),
+  };
+  stream.push({ type: "start", partial: output });
+
+  void (async () => {
+    let workspace: string | undefined;
+    let agent: Awaited<ReturnType<typeof Agent.create>> | undefined;
+    let run: Run | undefined;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let textIndex: number | undefined;
+    let reasoningIndex: number | undefined;
+    let delegated = false;
+
+    const endText = () => {
+      if (textIndex === undefined) return;
+      const index = textIndex;
+      stream.push({ type: "text_end", contentIndex: index, content: (output.content[index] as any).text, partial: output });
+      textIndex = undefined;
+    };
+    const endReasoning = () => {
+      if (reasoningIndex === undefined) return;
+      const index = reasoningIndex;
+      stream.push({ type: "thinking_end", contentIndex: index, content: (output.content[index] as any).thinking, partial: output });
+      reasoningIndex = undefined;
+    };
+    const textDelta = (delta: string) => {
+      if (!delta || delegated) return;
+      endReasoning();
+      if (textIndex === undefined) {
+        textIndex = output.content.length;
+        output.content.push({ type: "text", text: "" });
+        stream.push({ type: "text_start", contentIndex: textIndex, partial: output });
+      }
+      const index = textIndex;
+      (output.content[index] as any).text += delta;
+      stream.push({ type: "text_delta", contentIndex: index, delta, partial: output });
+    };
+    const reasoningDelta = (delta: string) => {
+      if (!delta || delegated) return;
+      endText();
+      if (reasoningIndex === undefined) {
+        reasoningIndex = output.content.length;
+        output.content.push({ type: "thinking", thinking: "" });
+        stream.push({ type: "thinking_start", contentIndex: reasoningIndex, partial: output });
+      }
+      const index = reasoningIndex;
+      (output.content[index] as any).thinking += delta;
+      stream.push({ type: "thinking_delta", contentIndex: index, delta, partial: output });
+    };
+
+    try {
+      const apiKey = options?.apiKey?.trim();
+      if (!apiKey) throw new Error("Cursor is not authenticated. Run `/login cursor`.");
+      if (options?.signal?.aborted) throw new Error("Cursor request cancelled.");
+      workspace = await mkdtemp(join(tmpdir(), "pi-cursor-sdk-"));
+      const customTools: Record<string, SDKCustomTool> = {};
+      for (const tool of context.tools ?? []) {
+        customTools[tool.name] = {
+          description: tool.description,
+          inputSchema: asJsonValue(tool.parameters ?? { type: "object" }) as Record<string, SDKJsonValue>,
+          async execute(args, toolContext) {
+            if (!delegated) {
+              delegated = true;
+              endText();
+              endReasoning();
+              const toolCall = {
+                type: "toolCall" as const,
+                id: toolContext.toolCallId || `cursor_${randomUUID()}`,
+                name: tool.name,
+                arguments: asArguments(args),
+              };
+              const contentIndex = output.content.length;
+              output.content.push(toolCall);
+              stream.push({ type: "toolcall_start", contentIndex, partial: output });
+              stream.push({ type: "toolcall_delta", contentIndex, delta: JSON.stringify(toolCall.arguments), partial: output });
+              stream.push({ type: "toolcall_end", contentIndex, toolCall, partial: output });
+              queueMicrotask(() => { void run?.cancel().catch(() => undefined); });
+            }
+            return { content: [{ type: "text", text: TOOL_DELEGATION_RESULT }], isError: true };
+          },
+        };
+      }
+
+      const selection = resolveCursorModelSelection(model, typeof options?.reasoning === "string" ? options.reasoning : undefined, loadCursorCatalog());
+      agent = await Agent.create({
+        apiKey,
+        model: selection,
+        tools: context.tools?.length ? ["mcp"] : [],
+        local: {
+          cwd: workspace,
+          store: new JsonlLocalAgentStore(join(workspace, "state")),
+          customTools,
+          enableAgentRetries: options?.maxRetries !== 0,
+        },
+      });
+
+      const request = serializeCursorContext(context);
+      run = await agent.send(request, {
+        idempotencyKey: options?.sessionId ? `${options.sessionId}-${randomUUID()}` : undefined,
+        onDelta: ({ update }) => {
+          if (update.type === "text-delta") textDelta(update.text);
+          else if (update.type === "thinking-delta") reasoningDelta(update.text);
+        },
+      });
+
+      const cancel = () => { void run?.cancel().catch(() => undefined); };
+      options?.signal?.addEventListener("abort", cancel, { once: true });
+      if (options?.timeoutMs && options.timeoutMs > 0) timeout = setTimeout(cancel, options.timeoutMs);
+      try {
+        for await (const event of run.stream()) {
+          if (event.type === "usage") usageFromCursor(event.usage, output);
+        }
+      } finally {
+        options?.signal?.removeEventListener("abort", cancel);
+      }
+      const result = await run.wait();
+      usageFromCursor(result.usage ?? run.usage, output);
+      endText();
+      endReasoning();
+
+      if (delegated) {
+        output.stopReason = "toolUse";
+      } else if (result.status === "cancelled") {
+        throw new Error(options?.signal?.aborted ? "Cursor request cancelled." : "Cursor request timed out or was cancelled.");
+      } else if (result.status === "error") {
+        throw new Error(result.error?.message ?? "Cursor returned an unsuccessful run.");
+      } else {
+        if (output.content.length === 0 && result.result) textDelta(result.result);
+        endText();
+        output.stopReason = "stop";
+      }
+      stream.push({ type: "done", reason: output.stopReason, message: output });
+      stream.end();
+    } catch (error) {
+      endText();
+      endReasoning();
+      if (delegated) {
+        output.stopReason = "toolUse";
+        stream.push({ type: "done", reason: "toolUse", message: output });
+      } else {
+        output.stopReason = options?.signal?.aborted ? "aborted" : "error";
+        output.errorMessage = formatCursorError(error);
+        stream.push({ type: "error", reason: output.stopReason, error: output });
+      }
+      stream.end();
+    } finally {
+      if (timeout) clearTimeout(timeout);
+      await disposeAgent(agent);
+      if (workspace) await rm(workspace, { recursive: true, force: true }).catch(() => undefined);
+    }
+  })();
+
+  return stream;
+}

package/extensions/cursor-provider/cursor/usage.ts

@@ -0,0 +1,165 @@
+import { Cursor, type ModelListItem } from "@cursor/sdk";
+import { CURSOR_BASE_URL } from "./models.ts";
+
+export interface CursorPlanInfo {
+  planName?: string;
+  includedAmountCents?: number;
+  price?: string;
+  billingCycleEnd?: number;
+}
+
+export interface CursorPlanUsage {
+  totalSpend: number;
+  includedSpend: number;
+  bonusSpend: number;
+  remaining: number;
+  limit: number;
+  autoSpend?: number;
+  apiSpend?: number;
+  autoLimit?: number;
+  apiLimit?: number;
+  autoPercentUsed?: number;
+  apiPercentUsed?: number;
+  totalPercentUsed?: number;
+}
+
+export interface CursorSpendLimitUsage {
+  totalSpend?: number;
+  individualLimit?: number;
+  individualUsed?: number;
+  individualRemaining?: number;
+  overallLimit?: number;
+  overallUsed?: number;
+  overallRemaining?: number;
+  limitType?: string;
+}
+
+export interface CursorUsageSnapshot {
+  email?: string;
+  apiKeyName?: string;
+  apiKeyCreatedAt?: number;
+  apiKeyExpiresAt?: number;
+  plan?: CursorPlanInfo;
+  usage?: CursorPlanUsage;
+  spendLimit?: CursorSpendLimitUsage;
+  billingCycleStart?: number;
+  billingCycleEnd?: number;
+  enabled: boolean;
+  displayMessage?: string;
+  canAdjustOnDemand: boolean;
+  currentOnDemandLimitCents?: number;
+  recommendedOnDemandLimitCents?: number;
+  models: ModelListItem[];
+  fetchedAt: number;
+}
+
+function numberValue(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value && Number.isFinite(Number(value))) return Number(value);
+  return undefined;
+}
+
+async function exchangeCursorApiKey(apiKey: string, signal?: AbortSignal): Promise<string> {
+  const response = await fetch(`${CURSOR_BASE_URL}/auth/exchange_user_api_key`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+    body: "{}",
+    signal,
+  });
+  if (!response.ok) throw new Error(response.status === 401 ? "Cursor API key is invalid." : `Cursor key exchange failed with HTTP ${response.status}.`);
+  const body = await response.json() as { accessToken?: unknown };
+  if (typeof body.accessToken !== "string" || !body.accessToken) throw new Error("Cursor key exchange returned no access token.");
+  return body.accessToken;
+}
+
+async function dashboardRpc(accessToken: string, method: string, body: Record<string, unknown> = {}, signal?: AbortSignal): Promise<Record<string, any>> {
+  const response = await fetch(`${CURSOR_BASE_URL}/aiserver.v1.DashboardService/${method}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      "Content-Type": "application/json",
+      "Connect-Protocol-Version": "1",
+    },
+    body: JSON.stringify(body),
+    signal,
+  });
+  if (!response.ok) throw new Error(`Cursor ${method} failed with HTTP ${response.status}.`);
+  return await response.json() as Record<string, any>;
+}
+
+export async function fetchCursorUsage(apiKey: string, signal?: AbortSignal): Promise<CursorUsageSnapshot> {
+  const accessToken = await exchangeCursorApiKey(apiKey, signal);
+  const [identity, models, period, plan, limits, keys] = await Promise.all([
+    Cursor.me({ apiKey }),
+    Cursor.models.list({ apiKey }),
+    dashboardRpc(accessToken, "GetCurrentPeriodUsage", { includePooledUsage: true }, signal),
+    dashboardRpc(accessToken, "GetPlanInfo", {}, signal),
+    dashboardRpc(accessToken, "GetUsageLimitStatusAndActiveGrants", {}, signal),
+    dashboardRpc(accessToken, "ListUserApiKeys", {}, signal),
+  ]);
+  const planUsage = period.planUsage as Record<string, unknown> | undefined;
+  const spendLimit = period.spendLimitUsage as Record<string, unknown> | undefined;
+  const planInfo = plan.planInfo as Record<string, unknown> | undefined;
+  const policy = limits.usageLimitPolicyStatus as Record<string, unknown> | undefined;
+  const listedKeys = Array.isArray(keys.apiKeys) ? keys.apiKeys as Array<Record<string, unknown>> : [];
+  const currentKey = listedKeys.find((entry) =>
+    (typeof entry.maskedKey === "string" && entry.maskedKey.endsWith(apiKey.slice(-4))) ||
+    entry.name === identity.apiKeyName
+  );
+
+  return {
+    email: identity.userEmail,
+    apiKeyName: identity.apiKeyName,
+    apiKeyCreatedAt: numberValue(currentKey?.createdAt),
+    apiKeyExpiresAt: numberValue(currentKey?.expiresAt),
+    plan: planInfo ? {
+      planName: typeof planInfo.planName === "string" ? planInfo.planName : undefined,
+      includedAmountCents: numberValue(planInfo.includedAmountCents),
+      price: typeof planInfo.price === "string" ? planInfo.price : undefined,
+      billingCycleEnd: numberValue(planInfo.billingCycleEnd),
+    } : undefined,
+    usage: planUsage ? {
+      totalSpend: numberValue(planUsage.totalSpend) ?? 0,
+      includedSpend: numberValue(planUsage.includedSpend) ?? 0,
+      bonusSpend: numberValue(planUsage.bonusSpend) ?? 0,
+      remaining: numberValue(planUsage.remaining) ?? 0,
+      limit: numberValue(planUsage.limit) ?? 0,
+      autoSpend: numberValue(planUsage.autoSpend),
+      apiSpend: numberValue(planUsage.apiSpend),
+      autoLimit: numberValue(planUsage.autoLimit),
+      apiLimit: numberValue(planUsage.apiLimit),
+      autoPercentUsed: numberValue(planUsage.autoPercentUsed),
+      apiPercentUsed: numberValue(planUsage.apiPercentUsed),
+      totalPercentUsed: numberValue(planUsage.totalPercentUsed),
+    } : undefined,
+    spendLimit: spendLimit ? {
+      totalSpend: numberValue(spendLimit.totalSpend),
+      individualLimit: numberValue(spendLimit.individualLimit),
+      individualUsed: numberValue(spendLimit.individualUsed),
+      individualRemaining: numberValue(spendLimit.individualRemaining),
+      overallLimit: numberValue(spendLimit.overallLimit),
+      overallUsed: numberValue(spendLimit.overallUsed),
+      overallRemaining: numberValue(spendLimit.overallRemaining),
+      limitType: typeof spendLimit.limitType === "string" ? spendLimit.limitType : undefined,
+    } : undefined,
+    billingCycleStart: numberValue(period.billingCycleStart),
+    billingCycleEnd: numberValue(period.billingCycleEnd),
+    enabled: period.enabled === true,
+    displayMessage: typeof period.displayMessage === "string" ? period.displayMessage : undefined,
+    canAdjustOnDemand: policy?.canAdjustOnDemand === true,
+    currentOnDemandLimitCents: numberValue(policy?.currentOnDemandLimitCents),
+    recommendedOnDemandLimitCents: numberValue(policy?.recommendedOnDemandLimitCents),
+    models: models.filter((model) => model.id !== "composer-2" && (model.id.startsWith("composer-") || /^grok-4\.(?:5|6)$/.test(model.id) || model.id.startsWith("cursor-grok-"))),
+    fetchedAt: Date.now(),
+  };
+}
+
+export function dollars(cents: number | undefined): string {
+  return typeof cents === "number" ? `$${(cents / 100).toFixed(2)}` : "unavailable";
+}
+
+export function percentUsed(snapshot: CursorUsageSnapshot): number | undefined {
+  if (typeof snapshot.usage?.totalPercentUsed === "number") return snapshot.usage.totalPercentUsed;
+  if (snapshot.usage?.limit) return snapshot.usage.totalSpend / snapshot.usage.limit * 100;
+  return undefined;
+}

package/extensions/cursor-provider/index.ts

@@ -0,0 +1,91 @@
+import type { OAuthCredentials } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loginCursor, refreshCursorToken } from "./cursor/auth.ts";
+import { openCursorDashboard, type CursorDashboardSnapshot } from "./cursor/dashboard.ts";
+import {
+  CURSOR_API,
+  CURSOR_BASE_URL,
+  CURSOR_PROVIDER_ID,
+  loadCursorCatalog,
+  toCursorPiModels,
+} from "./cursor/models.ts";
+import { streamCursorSdk } from "./cursor/stream.ts";
+import { fetchCursorUsage } from "./cursor/usage.ts";
+
+export default async function cursorProviderExtension(pi: ExtensionAPI) {
+  const catalog = loadCursorCatalog();
+  const models = toCursorPiModels(catalog);
+
+  pi.registerProvider(CURSOR_PROVIDER_ID, {
+    name: "Cursor",
+    baseUrl: CURSOR_BASE_URL,
+    api: CURSOR_API,
+    apiKey: "$CURSOR_API_KEY",
+    authHeader: true,
+    models,
+    oauth: {
+      name: "Cursor",
+      login: loginCursor,
+      refreshToken: refreshCursorToken,
+      getApiKey(credentials: OAuthCredentials) {
+        return credentials.access;
+      },
+    },
+    streamSimple: streamCursorSdk,
+  } as any);
+
+  const dashboardSnapshot = async (ctx: ExtensionContext): Promise<CursorDashboardSnapshot> => {
+    const auth = await ctx.modelRegistry.getProviderAuth(CURSOR_PROVIDER_ID);
+    const apiKey = auth?.auth.apiKey?.trim();
+    const authentication = auth?.source ?? "not authenticated";
+    if (!apiKey) return { authentication, error: "No Cursor credential is configured. Run `/login cursor` or set CURSOR_API_KEY." };
+    try {
+      return { authentication, usage: await fetchCursorUsage(apiKey, ctx.signal) };
+    } catch (error) {
+      return { authentication, error: error instanceof Error ? error.message : String(error) };
+    }
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    (ctx.modelRegistry as any).authStorage?.reload?.();
+  });
+
+  pi.registerCommand("cursor", {
+    description: "Open Cursor account, monthly usage, and limits dashboard",
+    handler: async (_args, ctx) => {
+      await openCursorDashboard(ctx, { authentication: ctx.modelRegistry.getProviderAuthStatus(CURSOR_PROVIDER_ID).source ?? "not authenticated" }, () => dashboardSnapshot(ctx));
+    },
+  });
+
+  pi.registerCommand("cursor.doctor", {
+    description: "Show sanitized Cursor provider diagnostics",
+    handler: async (_args, ctx) => {
+      const auth = ctx.modelRegistry.getProviderAuthStatus(CURSOR_PROVIDER_ID);
+      const text = [
+        `provider=${CURSOR_PROVIDER_ID}`,
+        "sdk=@cursor/sdk",
+        `authenticated=${auth.configured}`,
+        `authSource=${auth.source ?? "none"}`,
+        `catalogModels=${catalog.length}`,
+        `registeredModels=${models.length}`,
+        "oauth=pi-owned-browser-api-key",
+        "transport=native-cursor-sdk",
+        "images=true",
+        "nativeTools=true",
+        "acp=false",
+      ].join("\n");
+      if (ctx.hasUI) ctx.ui.notify(`Cursor doctor\n${text}`, "info");
+      console.log(text);
+    },
+  });
+
+  return {
+    deactivate: async () => {
+      try {
+        pi.unregisterProvider(CURSOR_PROVIDER_ID);
+      } catch {
+        // Ignore teardown after partial startup.
+      }
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shariq-pi-extensions",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Cross-platform extension suite for the Pi coding agent.",
   "license": "MIT",
   "author": "Shariq Riaz",
@@ -42,6 +42,7 @@
       "./extensions/background-terminals/index.ts",
       "./extensions/context-usage/index.ts",
       "./extensions/copy-all/index.ts",
+      "./extensions/cursor-provider/index.ts",
       "./extensions/factory-provider/index.ts",
       "./extensions/firecrawl-web/index.ts",
       "./extensions/git-info/index.ts",
@@ -71,6 +72,7 @@
     "prepublishOnly": "npm run validate"
   },
   "dependencies": {
+    "@cursor/sdk": "1.0.28",
     "@lydell/node-pty": "1.1.0",
     "effect": "4.0.0-beta.98",
     "ws": "8.21.3"
@@ -113,5 +115,8 @@
     "@google/genai": false,
     "protobufjs": false,
     "msgpackr-extract": false
+  },
+  "overrides": {
+    "undici": "6.28.0"
   }
 }