@justjoshn/pi-spacex-oauth-v2 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# pi-spacex-oauth-v2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use your X subscription in Pi through Grok Build and Cursor sign-ins. This extension needs Pi 1.5.2 or later.
+
+## Install
+
+Install it with:
+
+```sh
+pi install npm:@justjoshn/pi-spacex-oauth-v2
+```
+
+To try it from this checkout, use `pi -e extensions/pi-spacex-oauth-v2`.
+
+## Sign in and pick a model
+
+1. Start Pi and run `/login`.
+2. Choose **Grok Build (X subscription)** or **Cursor (X subscription)** and complete the sign-in prompts.
+3. Run `/model` and pick a `spacex-grok` or `spacex-cursor` model for the account you signed in with.
+
+Run `/login` again to sign in to the other provider if you use both. Run `/spacex-usage` to check the signed-in accounts' plan usage and the Grok Build rate limits returned by requests.
+
+## Access risks
+
+The extension uses undocumented Grok Build and Cursor endpoints and identifies requests as their clients. Vendor changes to those endpoints, client requirements, or account access can break sign-in or requests. Use only accounts you own.

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@justjoshn/pi-spacex-oauth-v2",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Use your X/SpaceX subscription in pi through Grok Build and Cursor CLI sign-ins.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/just-joshn/pi-customizations.git",
+    "directory": "extensions/pi-spacex-oauth-v2"
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.5.2",
+    "@earendil-works/pi-coding-agent": "1.5.2",
+    "vitest": "5.1.0",
+    "@vitest/coverage-v8": "5.1.0"
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,20 @@
+import type { AnyModel, RefreshModelsContext } from '@earendil-works/pi-ai';
+import type { ProviderModelConfig } from '@earendil-works/pi-coding-agent';
+
+/**
+ * Fetches the live model list when pi allows network access and persists it, so print mode and
+ * offline starts (which refresh without network) still see every model from the last live fetch.
+ */
+export async function refreshCatalog(
+  ctx: RefreshModelsContext,
+  target: { provider: string; api: string; baseUrl: string },
+  fallback: ProviderModelConfig[],
+  fetchLive: (accessToken: string, signal: AbortSignal) => Promise<ProviderModelConfig[]>,
+): Promise<ProviderModelConfig[]> {
+  const stored = ctx.stored?.models as ProviderModelConfig[] | undefined;
+  if (!ctx.allowNetwork || ctx.credential?.type !== 'oauth') return stored ?? fallback;
+  const models = await fetchLive(ctx.credential.access, ctx.signal);
+  const persisted = models.map((m) => ({ ...target, ...m }) as unknown as AnyModel);
+  await ctx.publish({ persist: { models: persisted, checkedAt: Date.now() } });
+  return models;
+}

package/src/cursor/auth.ts

@@ -0,0 +1,73 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+
+import type { OAuthCredentials, OAuthLoginCallbacks } from '@earendil-works/pi-ai';
+
+export const CURSOR_API = 'https://api2.cursor.sh';
+const CURSOR_WEBSITE = 'https://cursor.com';
+// The production auth client id the Cursor IDE uses to refresh browser sign-ins.
+const CURSOR_CLIENT_ID = 'KbZUR41cY7W6zRSdpSUJ7I7mLYBKOCmB';
+
+const base64url = (buf: Buffer) => buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+
+export function jwtExpiry(token: string): number {
+  const payload = token.split('.')[1];
+  if (!payload) throw new Error('Cursor returned a token that is not a JWT');
+  const { exp } = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as { exp?: number };
+  if (!exp) throw new Error('Cursor token has no expiry');
+  return exp * 1000;
+}
+
+export function loginUrl(challenge: string, uuid: string): string {
+  const url = new URL('/loginDeepControl', CURSOR_WEBSITE);
+  url.searchParams.set('challenge', challenge);
+  url.searchParams.set('uuid', uuid);
+  url.searchParams.set('mode', 'login');
+  url.searchParams.set('redirectTarget', 'cli');
+  return url.toString();
+}
+
+const sleep = (ms: number, signal?: AbortSignal) =>
+  new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+
+export async function cursorLogin(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash('sha256').update(verifier).digest());
+  const uuid = randomUUID();
+  callbacks.onAuth({ url: loginUrl(challenge, uuid), instructions: 'Sign in to Cursor in the browser, then return here.' });
+  // Same schedule as cursor-agent: 404 means not approved yet, back off 1s * 1.2^n up to 10s, 150 tries.
+  for (let attempt = 0; attempt < 150; attempt++) {
+    const res = await fetch(`${CURSOR_API}/auth/poll?uuid=${uuid}&verifier=${verifier}`, { ...(callbacks.signal ? { signal: callbacks.signal } : {}) });
+    if (res.ok) {
+      const body = (await res.json()) as { accessToken?: string; refreshToken?: string };
+      if (!body.accessToken || !body.refreshToken) throw new Error('Cursor sign-in finished without a Cursor access token');
+      return { access: body.accessToken, refresh: body.refreshToken, expires: jwtExpiry(body.accessToken) };
+    }
+    if (res.status !== 404) throw new Error(`Cursor sign-in failed: HTTP ${res.status}`);
+    await sleep(Math.min(1000 * 1.2 ** attempt, 10_000), callbacks.signal);
+  }
+  throw new Error('Cursor sign-in timed out before it was approved');
+}
+
+export async function cursorRefresh(credentials: OAuthCredentials, signal: AbortSignal): Promise<OAuthCredentials> {
+  const res = await fetch(`${CURSOR_API}/oauth/token`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ grant_type: 'refresh_token', client_id: CURSOR_CLIENT_ID, refresh_token: credentials.refresh }),
+    signal,
+  });
+  if (!res.ok && res.status >= 500) throw new Error(`Cursor token refresh failed: HTTP ${res.status}`);
+  const body = (await res.json()) as { access_token?: string; refresh_token?: string; shouldLogout?: boolean; error?: string };
+  if (body.shouldLogout) throw new Error(`Cursor ended this sign-in${body.error ? `: ${body.error}` : ''}. Run /login again.`);
+  if (!body.access_token) throw new Error(`Cursor token refresh failed: HTTP ${res.status}`);
+  return { ...credentials, access: body.access_token, refresh: body.refresh_token ?? credentials.refresh, expires: jwtExpiry(body.access_token) };
+}

package/src/cursor/models.ts

@@ -0,0 +1,101 @@
+import type { ProviderModelConfig } from '@earendil-works/pi-coding-agent';
+import { CURSOR_API } from './auth.ts';
+
+export const CURSOR_CLIENT_VERSION = 'cli-2026.11.13-eacade1';
+export const cursorHeaders = (token: string) => ({
+  authorization: `Bearer ${token}`,
+  'x-cursor-client-type': 'cli',
+  'x-cursor-client-version': CURSOR_CLIENT_VERSION,
+  'x-ghost-mode': 'true',
+});
+
+const EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+type Effort = (typeof EFFORTS)[number];
+const EFFORT_WORDS = /\s+(None|Minimal|Low|Medium|High|Extra High|Max)(?=\s+Thinking|\s+Fast|\s+\(|$)/;
+
+export interface CursorModelDetails {
+  modelId: string;
+  displayName?: string;
+}
+
+interface Variant {
+  id: string;
+  effort?: Effort;
+  displayName: string;
+}
+
+/** Splits a flat Cursor id like `claude-opus-5-5-high-fast` into its pi model id and effort. */
+export function parseVariant(id: string): { piId: string; effort?: Effort } {
+  const fast = id.endsWith('-fast');
+  const stem = fast ? id.slice(0, -5) : id;
+  const effort = EFFORTS.find((e) => stem.endsWith(`-${e}`));
+  const base = effort ? stem.slice(0, -(effort.length + 1)) : stem;
+  return { piId: fast ? `${base}-fast` : base, ...(effort ? { effort } : {}) };
+}
+
+const cleanName = (name: string) => name.replace(/[​-‍]/g, '').replace(/\s+/g, ' ').trim();
+
+/**
+ * Collapses Cursor's per-effort ids into one pi model per base id (and one per `-fast` base).
+ * The pi thinking level picks the variant through thinkingLevelMap, whose values are real Cursor ids.
+ */
+export function collapseModels(models: CursorModelDetails[]): ProviderModelConfig[] {
+  const groups = new Map<string, Variant[]>();
+  for (const m of models) {
+    if (m.modelId === 'default') continue;
+    const { piId, effort } = parseVariant(m.modelId);
+    groups.set(piId, [...(groups.get(piId) ?? []), { id: m.modelId, ...(effort ? { effort } : {}), displayName: cleanName(m.displayName ?? m.modelId) }]);
+  }
+  const out: ProviderModelConfig[] = [{ id: 'auto', name: 'Auto', reasoning: false, input: ['text'], cost: zeroCost, contextWindow: 200_000, maxTokens: 64_000 }];
+  for (const [piId, variants] of groups) {
+    const plain = variants.find((v) => !v.effort);
+    const byEffort = new Map(variants.filter((v) => v.effort).map((v) => [v.effort as Effort, v.id]));
+    const named = plain ?? variants.find((v) => v.effort === 'high') ?? variants[0];
+    const name = (named?.displayName ?? piId).replace(EFFORT_WORDS, '');
+    out.push({
+      id: piId,
+      name,
+      reasoning: byEffort.size > 0,
+      ...(byEffort.size > 0
+        ? {
+            thinkingLevelMap: {
+              off: plain?.id ?? byEffort.get('none') ?? null,
+              minimal: byEffort.get('minimal') ?? null,
+              low: byEffort.get('low') ?? null,
+              medium: byEffort.get('medium') ?? null,
+              high: byEffort.get('high') ?? null,
+              xhigh: byEffort.get('xhigh') ?? null,
+              max: byEffort.get('max') ?? null,
+            },
+          }
+        : {}),
+      input: ['text'],
+      cost: zeroCost,
+      contextWindow: /\b1M\b/.test(name) ? 1_000_000 : 200_000,
+      maxTokens: 64_000,
+    });
+  }
+  return out;
+}
+
+const zeroCost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+
+/** The Cursor id to request for a pi model at a pi thinking level. */
+export function resolveCursorModelId(piId: string, map: Partial<Record<string, string | null>> | undefined, level: string | undefined): string {
+  if (piId === 'auto') return 'default';
+  if (!map) return piId;
+  const pick = (l: string) => map[l] ?? undefined;
+  return pick(level ?? 'off') ?? pick('medium') ?? pick('high') ?? pick('low') ?? Object.values(map).find((v): v is string => !!v) ?? piId;
+}
+
+export async function fetchCursorModels(token: string, signal?: AbortSignal): Promise<ProviderModelConfig[]> {
+  const res = await fetch(`${CURSOR_API}/agent.v1.AgentService/GetUsableModels`, {
+    method: 'POST',
+    headers: { ...cursorHeaders(token), 'content-type': 'application/json', 'connect-protocol-version': '1' },
+    body: '{}',
+    ...(signal ? { signal } : {}),
+  });
+  if (!res.ok) throw new Error(`Cursor model list failed: HTTP ${res.status}`);
+  const body = (await res.json()) as { models?: CursorModelDetails[] };
+  return collapseModels(body.models ?? []);
+}

package/src/cursor/proto.ts

@@ -0,0 +1,194 @@
+// Minimal protobuf wire codec and Connect envelope framing for the agent.v1 messages the bridge uses.
+// Field numbers come from the schema embedded in cursor-agent (scripts/extract-cursor-schema.mjs).
+import { gunzipSync } from 'node:zlib';
+
+/** A message is a list of [field number, value]; nested messages are Field[] themselves. */
+export type Field = [number, FieldValue];
+export type FieldValue = string | number | boolean | Uint8Array | Field[] | undefined;
+
+function varint(n: number | bigint, out: number[]) {
+  let v = BigInt(n);
+  if (v < 0n) v += 1n << 64n;
+  while (v > 0x7fn) {
+    out.push(Number(v & 0x7fn) | 0x80);
+    v >>= 7n;
+  }
+  out.push(Number(v));
+}
+
+export function encode(fields: Field[]): Uint8Array {
+  const out: number[] = [];
+  for (const [no, value] of fields) {
+    if (value === undefined) continue;
+    if (typeof value === 'number' || typeof value === 'boolean') {
+      varint((no << 3) | 0, out);
+      varint(typeof value === 'boolean' ? Number(value) : value, out);
+      continue;
+    }
+    const bytes = typeof value === 'string' ? new TextEncoder().encode(value) : value instanceof Uint8Array ? value : encode(value);
+    varint((no << 3) | 2, out);
+    varint(bytes.length, out);
+    for (const b of bytes) out.push(b);
+  }
+  return Uint8Array.from(out);
+}
+
+/** Doubles need wire type 1, which `encode` never infers; used only for google.protobuf.Value numbers. */
+function double(no: number, n: number): Uint8Array {
+  const buf = new Uint8Array(9);
+  buf[0] = (no << 3) | 1;
+  new DataView(buf.buffer).setFloat64(1, n, true);
+  return buf;
+}
+
+export interface Decoded {
+  varints: Map<number, bigint[]>;
+  bytes: Map<number, Uint8Array[]>;
+  fixed64: Map<number, Uint8Array[]>;
+}
+
+export function decode(buf: Uint8Array): Decoded {
+  const d: Decoded = { varints: new Map(), bytes: new Map(), fixed64: new Map() };
+  let pos = 0;
+  const readVarint = () => {
+    let shift = 0n;
+    let result = 0n;
+    for (;;) {
+      const b = buf[pos++];
+      if (b === undefined) throw new Error('truncated protobuf varint');
+      result |= BigInt(b & 0x7f) << shift;
+      if ((b & 0x80) === 0) return result;
+      shift += 7n;
+    }
+  };
+  const push = <T>(map: Map<number, T[]>, no: number, v: T) => map.set(no, [...(map.get(no) ?? []), v]);
+  while (pos < buf.length) {
+    const tag = Number(readVarint());
+    const no = tag >>> 3;
+    switch (tag & 7) {
+      case 0:
+        push(d.varints, no, readVarint());
+        break;
+      case 1:
+        if (pos + 8 > buf.length) throw new Error('truncated protobuf field');
+        push(d.fixed64, no, buf.subarray(pos, pos + 8));
+        pos += 8;
+        break;
+      case 2: {
+        const len = Number(readVarint());
+        if (pos + len > buf.length) throw new Error('truncated protobuf field');
+        push(d.bytes, no, buf.subarray(pos, pos + len));
+        pos += len;
+        break;
+      }
+      case 5:
+        if (pos + 4 > buf.length) throw new Error('truncated protobuf field');
+        pos += 4;
+        break;
+      default:
+        throw new Error(`unsupported protobuf wire type ${tag & 7}`);
+    }
+  }
+  return d;
+}
+
+export const str = (d: Decoded, no: number) => {
+  const b = d.bytes.get(no)?.[0];
+  return b ? new TextDecoder().decode(b) : '';
+};
+export const msg = (d: Decoded, no: number) => {
+  const b = d.bytes.get(no)?.[0];
+  return b ? decode(b) : undefined;
+};
+export const num = (d: Decoded, no: number) => Number(d.varints.get(no)?.[0] ?? 0n);
+export const raw = (d: Decoded, no: number) => d.bytes.get(no)?.[0];
+
+// google.protobuf.Value, used for MCP tool schemas and arguments.
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+export function encodeValue(v: Json): Uint8Array {
+  if (v === null) return encode([[1, 0]]);
+  if (typeof v === 'number') return double(2, v);
+  if (typeof v === 'string') return encode([[3, v]]);
+  if (typeof v === 'boolean') return encode([[4, v]]);
+  if (Array.isArray(v)) return encode([[6, v.map((x): Field => [1, encodeValue(x)])]]);
+  return encode([
+    [
+      5,
+      Object.entries(v).map(
+        ([k, x]): Field => [
+          1,
+          [
+            [1, k],
+            [2, encodeValue(x)],
+          ],
+        ],
+      ),
+    ],
+  ]);
+}
+
+export function decodeValue(buf: Uint8Array): Json {
+  const d = decode(buf);
+  const f64 = d.fixed64.get(2)?.[0];
+  if (f64) return new DataView(f64.buffer, f64.byteOffset, 8).getFloat64(0, true);
+  if (d.bytes.has(3)) return str(d, 3);
+  if (d.varints.has(4)) return num(d, 4) !== 0;
+  const struct = raw(d, 5);
+  if (struct) return decodeStruct(struct);
+  const list = raw(d, 6);
+  if (list) return (decode(list).bytes.get(1) ?? []).map(decodeValue);
+  return null;
+}
+
+function decodeStruct(buf: Uint8Array): { [key: string]: Json } {
+  const out: { [key: string]: Json } = {};
+  for (const entry of decode(buf).bytes.get(1) ?? []) {
+    const e = decode(entry);
+    const value = raw(e, 2);
+    out[str(e, 1)] = value ? decodeValue(value) : null;
+  }
+  return out;
+}
+
+/** Decodes a protobuf map<string, google.protobuf.Value> field into a plain object. */
+export function decodeValueMap(d: Decoded, no: number): { [key: string]: Json } {
+  const out: { [key: string]: Json } = {};
+  for (const entry of d.bytes.get(no) ?? []) {
+    const e = decode(entry);
+    const value = raw(e, 2);
+    out[str(e, 1)] = value ? decodeValue(value) : null;
+  }
+  return out;
+}
+
+// Connect streaming envelopes: 1 flag byte (bit 0 compressed, bit 1 end-stream) + 4-byte big-endian length.
+export function frame(payload: Uint8Array): Uint8Array {
+  const out = new Uint8Array(5 + payload.length);
+  new DataView(out.buffer).setUint32(1, payload.length);
+  out.set(payload, 5);
+  return out;
+}
+
+export type Envelope = { end: false; payload: Uint8Array } | { end: true; json: string };
+
+export class EnvelopeReader {
+  private buf = new Uint8Array(0);
+  push(chunk: Uint8Array): Envelope[] {
+    const merged = new Uint8Array(this.buf.length + chunk.length);
+    merged.set(this.buf);
+    merged.set(chunk, this.buf.length);
+    this.buf = merged;
+    const out: Envelope[] = [];
+    while (this.buf.length >= 5) {
+      const flags = this.buf[0] ?? 0;
+      const len = new DataView(this.buf.buffer, this.buf.byteOffset).getUint32(1);
+      if (this.buf.length < 5 + len) break;
+      let payload: Uint8Array = this.buf.slice(5, 5 + len);
+      this.buf = this.buf.slice(5 + len);
+      if (flags & 1) payload = gunzipSync(payload);
+      out.push(flags & 2 ? { end: true, json: new TextDecoder().decode(payload) } : { end: false, payload });
+    }
+    return out;
+  }
+}

package/src/cursor/provider.ts

@@ -0,0 +1,30 @@
+import type { ProviderConfig } from '@earendil-works/pi-coding-agent';
+import { refreshCatalog } from '../catalog.ts';
+import { cursorLogin, cursorRefresh } from './auth.ts';
+import { collapseModels, fetchCursorModels } from './models.ts';
+import { AGENT_URL } from './run.ts';
+import { streamCursor } from './stream.ts';
+
+export const CURSOR_PROVIDER_ID = 'spacex-cursor';
+
+// Composer and Auto until the first live refresh replaces the list with GetUsableModels.
+const FALLBACK_MODELS = collapseModels([
+  { modelId: 'composer-2.5', displayName: 'Composer 2.5' },
+  { modelId: 'composer-2.5-fast', displayName: 'Composer 2.5 Fast' },
+]);
+
+export const cursorProvider: ProviderConfig = {
+  name: 'Cursor (X subscription)',
+  baseUrl: AGENT_URL,
+  api: 'cursor-agent',
+  streamSimple: streamCursor,
+  models: FALLBACK_MODELS,
+  refreshModels: (ctx) => refreshCatalog(ctx, { provider: CURSOR_PROVIDER_ID, api: 'cursor-agent', baseUrl: AGENT_URL }, FALLBACK_MODELS, fetchCursorModels),
+  oauth: {
+    name: 'Cursor (X subscription)',
+    isSubscription: true,
+    login: cursorLogin,
+    refreshToken: cursorRefresh,
+    getApiKey: (credentials) => credentials.access,
+  },
+};