pi-devin-auth 0.1.0

package/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md — pi-devin-auth
+
+## Overview
+
+A [pi](https://pi.dev) coding agent extension that registers the `devin` provider (Cognition / Windsurf) with OAuth login and native streaming. Reuses the cloud-direct gRPC layer from `opencode-windsurf-auth`.
+
+## Architecture
+
+```
+extensions/index.ts          # pi extension entry — registerProvider("devin", { oauth, streamSimple, models })
+src/oauth/
+  login.ts                   # ADAPTED — pi OAuthLoginCallbacks (manual-paste flow)
+  register-user.ts           # COPIED verbatim — RegisterUser RPC at register.windsurf.com
+  types.ts                   # COPIED verbatim — WindsurfRegion, DEFAULT_REGION
+src/cloud-direct/            # COPIED verbatim — gRPC to server.codeium.com
+  auth.ts                    #   GetUserJwt (short-lived JWT mint + in-memory cache)
+  chat.ts                    #   GetChatMessage streaming (Connect-RPC + manual protobuf)
+  catalog.ts                 #   GetCascadeModelConfigs (per-account model catalog)
+  metadata.ts                #   Metadata proto builder
+  wire.ts                    #   Protobuf + Connect-streaming envelope helpers
+  index.ts                   #   Public re-exports
+src/context-map.ts           # NEW — pi Message[]/Tool[] -> ChatHistoryItem[]/ToolDef[]
+src/stream.ts                # NEW — streamDevin: streamSimple impl (CloudChatEvent -> pi events)
+src/models.ts                # NEW — dynamic catalog -> ProviderModelConfig[] + fallback
+```
+
+## Build & Test
+
+```bash
+npm install          # install deps
+npx tsc --noEmit     # typecheck
+npm test             # run unit tests (bun test or node --test)
+```
+
+pi loads extensions via jiti (no build step needed for runtime use).
+
+## Key Design Decisions
+
+1. **Native streamSimple** (Option B): No background proxy. `streamDevin()` calls `streamChatEvents()` directly and emits pi's `AssistantMessageEventStream` events.
+2. **Manual-paste OAuth**: pi's `OAuthLoginCallbacks` doesn't support loopback servers. We use `redirect_uri=show-auth-token` so the Windsurf SPA renders the token for the user to paste via `callbacks.onPrompt()`.
+3. **Non-expiring token shape**: Windsurf's `RegisterUser` returns a long-lived `api_key` with no refresh token. We set `OAuthCredentials = { refresh: "", access: apiKey, expires: now + 365 days }`. `refreshToken()` is a no-op.
+4. **Dynamic model catalog**: Fetched from `GetCascadeModelConfigs` via `oauth.modifyModels()` after login. Static fallback for offline.
+5. **In-memory JWT cache only**: No disk persistence for the short-lived `user_jwt`. Re-mint cost (~200ms) is negligible.
+
+## Token Shapes
+
+- **firebaseIdToken**: Short-lived JWT from Auth0 browser sign-in. Exchanged via RegisterUser, then discarded.
+- **api_key**: Long-lived credential from RegisterUser. Format: `devin-session-token$<JWT>`. Used as `Metadata.api_key` in every gRPC call. Stored by pi in `~/.pi/agent/auth.json`.
+- **user_jwt**: Short-lived (~24 min) JWT minted from `GetUserJwt`. Cached in-memory per (apiKey, host). Required alongside api_key for chat RPCs.
+
+## Cloud-Direct gRPC
+
+All RPCs hit `https://server.codeium.com` over HTTPS with Connect-RPC framing:
+- `GetUserJwt` — unary, `application/proto`
+- `GetCascadeModelConfigs` — unary, `application/proto`
+- `GetChatMessage` — streaming, `application/connect+proto` (gzip-compressed frames)
+
+Manual protobuf encoding (no protobuf library). Field numbers hardcoded from mitm captures of Windsurf's language_server traffic.
+
+## Related
+
+- [opencode-windsurf-auth](https://github.com/rsvedant/opencode-windsurf-auth) — the opencode plugin this is derived from
+- [pi custom-provider docs](https://pi.dev/docs/latest/custom-provider)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nmzpy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# pi-devin-auth
+
+A [pi](https://pi.dev) coding agent extension that adds the **Devin** (Cognition / Windsurf) provider with browser-based OAuth login and native streaming.
+
+## Install
+
+### Via pi (recommended)
+
+```bash
+pi install npm:pi-devin-auth
+```
+
+Then enable the extension:
+
+```bash
+pi config
+```
+
+### Manual / local dev
+
+```bash
+pi -e ./extensions/index.ts
+```
+
+Or copy `extensions/index.ts` into `~/.pi/agent/extensions/` for auto-discovery.
+
+## Usage
+
+### Login
+
+```
+/login devin
+```
+
+This opens `https://windsurf.com/windsurf/signin` in your browser. After signing in, the page displays an auth token — paste it into the pi prompt. The extension exchanges it for a long-lived Devin API key via `register.windsurf.com`.
+
+### Select a model
+
+```
+/model devin/swe-1-6
+```
+
+### Logout
+
+```
+/logout devin
+```
+
+## How it works
+
+```
+pi  --login-->  windsurf.com (Auth0)  --token-->  register.windsurf.com (RegisterUser)  --api_key-->  ~/.pi/agent/auth.json
+pi  --chat-->   streamDevin()  -->  cloud-direct/streamChatEvents()  -->  server.codeium.com (GetChatMessage gRPC)  -->  pi events
+```
+
+The extension reuses the battle-tested cloud-direct gRPC layer from [opencode-windsurf-auth](https://github.com/rsvedant/opencode-windsurf-auth) and wraps it in pi's native `streamSimple` + `oauth` extension API.
+
+## Models
+
+Models are fetched dynamically from Cognition's `GetCascadeModelConfigs` RPC after login, so the list always reflects what your account tier can access. A static fallback set is included for offline use.
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,69 @@
+/**
+ * pi extension entry point for the Devin (Cognition) provider.
+ *
+ * Registers the `devin` provider with pi's ExtensionAPI, wiring up:
+ *  - OAuth login via Windsurf's browser sign-in flow (`loginDevin`)
+ *  - A no-op token refresh (Windsurf api_keys are long-lived)
+ *  - Static model list (dynamic catalog fetch planned for a future version
+ *    once we've inspected the gRPC GetCascadeModelConfigs response shape)
+ *  - Streaming chat completions through Devin Cloud (`streamDevin`)
+ *
+ * The provider does not set baseUrl/apiKey at the provider level —
+ * `streamSimple` handles all routing and auth internally using the
+ * OAuth-issued api_key.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type {
+    Api,
+    Model,
+    OAuthCredentials,
+    OAuthLoginCallbacks,
+} from '@earendil-works/pi-ai';
+import { streamDevin } from '../src/stream.js';
+import { loginDevin } from '../src/oauth/login.js';
+import { FALLBACK_MODELS } from '../src/models.js';
+import { DEFAULT_REGION } from '../src/oauth/types.js';
+
+const PROVIDER_ID = 'devin';
+const PROVIDER_NAME = 'Devin (Cognition)';
+const OAUTH_NAME = 'Devin (Cognition / Windsurf)';
+const API_IDENTIFIER = 'devin-cloud';
+
+export default async function (pi: ExtensionAPI): Promise<void> {
+    pi.registerProvider(PROVIDER_ID, {
+        name: PROVIDER_NAME,
+        api: API_IDENTIFIER,
+        // No baseUrl/apiKey at the provider level — streamSimple handles
+        // all routing and auth internally via the OAuth-issued api_key.
+        models: FALLBACK_MODELS,
+        oauth: {
+            name: OAUTH_NAME,
+            async login(
+                callbacks: OAuthLoginCallbacks,
+            ): Promise<OAuthCredentials> {
+                return loginDevin(callbacks, DEFAULT_REGION);
+            },
+            async refreshToken(
+                credentials: OAuthCredentials,
+            ): Promise<OAuthCredentials> {
+                // Windsurf's RegisterUser returns a long-lived api_key
+                // with no refresh token. The key is effectively
+                // non-expiring, so refreshToken is a no-op — return the
+                // same credentials.
+                return credentials;
+            },
+            getApiKey(credentials: OAuthCredentials): string {
+                return credentials.access;
+            },
+            // modifyModels is sync in pi v0.80.x, so we can't do an async
+            // catalog fetch here. The static FALLBACK_MODELS list is used
+            // for v0.1.0. Dynamic catalog fetch will be added in a future
+            // version once we've verified the gRPC response shape.
+            modifyModels(models: Model<Api>[]): Model<Api>[] {
+                return models;
+            },
+        },
+        streamSimple: streamDevin,
+    });
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "pi-devin-auth",
+  "version": "0.1.0",
+  "description": "Pi coding agent extension for Devin/Cognition (Windsurf) OAuth + streaming",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "devin",
+    "cognition",
+    "windsurf",
+    "oauth",
+    "pi-extension",
+    "custom-provider"
+  ],
+  "author": "nmzpy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nmzpy/pi-devin-auth.git"
+  },
+  "homepage": "https://github.com/nmzpy/pi-devin-auth#readme",
+  "bugs": {
+    "url": "https://github.com/nmzpy/pi-devin-auth/issues"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "files": [
+    "extensions/",
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx tests/stream.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^25.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cloud-direct/auth.ts

@@ -0,0 +1,246 @@
+/**
+ * Mint the short-lived `user_jwt` that every chat RPC needs alongside the
+ * persistent OAuth-issued `api_key`.
+ *
+ *   POST https://server.codeium.com/exa.auth_pb.AuthService/GetUserJwt
+ *   Content-Type: application/proto             ← unary, NOT streaming
+ *   Body: GetUserJwtRequest { metadata: Metadata }
+ *   Response: GetUserJwtResponse { user_jwt: string }  (field 1)
+ *
+ * The returned JWT has a payload like:
+ *   {
+ *     "api_key": "devin-synthetic-apikey$account-…$user-…",
+ *     "auth_uid": "devin-auth-uid$…",
+ *     "email": "user@example.com",
+ *     "exp": <unix-seconds>,         ← ~24 minute TTL
+ *     "pro": true,
+ *     "teams_tier": "TEAMS_TIER_DEVIN_PRO",
+ *     ...
+ *   }
+ *
+ * The JWT is signed HS256 by the server — can't be forged client-side. We
+ * cache it and refresh shortly before `exp`.
+ */
+
+import * as crypto from 'crypto';
+import { encodeMessage, iterFields } from './wire.js';
+import { buildMetadata } from './metadata.js';
+
+const DEFAULT_HOST = 'https://server.codeium.com';
+
+/**
+ * Polyfill for `AbortSignal.any` — composes multiple signals so the result
+ * aborts when ANY input aborts. Built-in in Node ≥20.3 / Bun ≥1.0. Our
+ * `engines.node` is `>=18.0.0`, so we ship the fallback ourselves; without
+ * it the caller's cancel signal silently disappears on older runtimes
+ * (chat-cancel during a `GetUserJwt` mint would keep the network request
+ * alive for up to the full 30s timeout).
+ */
+function anySignal(signals: AbortSignal[]): AbortSignal {
+  const builtin = (AbortSignal as unknown as { any?: (s: AbortSignal[]) => AbortSignal }).any;
+  if (typeof builtin === 'function') return builtin(signals);
+  const controller = new AbortController();
+  const onAbort = (reason: unknown): void => {
+    if (!controller.signal.aborted) controller.abort(reason);
+  };
+  for (const s of signals) {
+    if (s.aborted) {
+      onAbort(s.reason);
+      break;
+    }
+    s.addEventListener('abort', () => onAbort(s.reason), { once: true });
+  }
+  return controller.signal;
+}
+
+export interface MintedUserJwt {
+  jwt: string;
+  /** Unix epoch seconds when the JWT expires. */
+  expiresAt: number;
+}
+
+export class CloudAuthError extends Error {
+  constructor(message: string, public readonly status?: number) {
+    super(message);
+    this.name = 'CloudAuthError';
+  }
+}
+
+/**
+ * Default mint timeout — 30s is generous (the endpoint responds in ~200ms
+ * in steady state) but enough headroom for slow networks. Callers can pass
+ * a tighter `signal` to override.
+ */
+const MINT_TIMEOUT_MS = 30_000;
+
+/**
+ * Mint a fresh user_jwt by calling exa.auth_pb.AuthService/GetUserJwt.
+ * `host` defaults to https://server.codeium.com — pass your tenant URL if your
+ * RegisterUser response gave a different host.
+ *
+ * Always applies an internal 30s timeout so a network stall here can't
+ * deadlock every concurrent chat request. If the caller passes a `signal`,
+ * we honor whichever fires first via AbortSignal.any.
+ */
+export async function mintUserJwt(
+  apiKey: string,
+  host: string = DEFAULT_HOST,
+  signal?: AbortSignal,
+): Promise<MintedUserJwt> {
+  const metadata = buildMetadata({
+    apiKey,
+    sessionId: crypto.randomUUID(),
+    requestId: BigInt(Date.now()),
+    triggerId: crypto.randomUUID(),
+  });
+  // GetUserJwtRequest { metadata: Metadata }   — Metadata is field 1
+  const req = encodeMessage(1, metadata);
+
+  // Compose caller signal with our internal timeout via `anySignal` — a
+  // small polyfill of `AbortSignal.any` for runtimes (Node 18 / older
+  // Bun) that lack the built-in. The previous fallback silently dropped
+  // the CALLER's signal on those runtimes, so a chat-cancel during a
+  // GetUserJwt mint would keep the network request alive for up to the
+  // full 30s timeout.
+  const timeoutSignal = AbortSignal.timeout(MINT_TIMEOUT_MS);
+  const combinedSignal: AbortSignal = signal
+    ? anySignal([signal, timeoutSignal])
+    : timeoutSignal;
+
+  const resp = await fetch(`${host.replace(/\/$/, '')}/exa.auth_pb.AuthService/GetUserJwt`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/proto',
+      'Connect-Protocol-Version': '1',
+    },
+    body: req,
+    signal: combinedSignal,
+  });
+  const buf = Buffer.from(await resp.arrayBuffer());
+
+  if (!resp.ok) {
+    const text = buf.toString('utf8');
+    throw new CloudAuthError(`GetUserJwt HTTP ${resp.status}: ${text.slice(0, 400)}`, resp.status);
+  }
+
+  // Response is GetUserJwtResponse { user_jwt: string } where user_jwt is
+  // field 1, length-delimited. Decode the field properly instead of
+  // regex-scanning the whole buffer — the previous regex would pick up
+  // any JWT-shaped substring in the response (trace IDs, signature
+  // headers, any cached token inadvertently logged) and could even land
+  // on a non-user_jwt if Cognition ever embeds another JWT in a sibling
+  // field.
+  let jwt: string | null = null;
+  for (const f of iterFields(buf)) {
+    if (f.num === 1 && f.wire === 2 && Buffer.isBuffer(f.value)) {
+      const s = (f.value as Buffer).toString('utf8');
+      // Sanity-check the shape — defensive: if the cloud ever moves user_jwt
+      // out from field 1 we want a clean error, not silently wrong creds.
+      // base64url with OPTIONAL `=` padding on each segment. Most modern
+      // JWTs omit the `=`, but the spec allows it and a future server-side
+      // change could re-introduce it; either way it's still a valid token.
+      if (/^eyJ[A-Za-z0-9_-]{10,}={0,2}\.[A-Za-z0-9_-]+={0,2}\.[A-Za-z0-9_-]+={0,2}$/.test(s)) {
+        jwt = s;
+        break;
+      }
+    }
+  }
+  if (!jwt) {
+    throw new CloudAuthError(
+      `GetUserJwt 200 but no field-1 JWT found (${buf.length} bytes): ${buf.toString('utf8').slice(0, 200)}`,
+    );
+  }
+
+  // Decode the payload to get the expiry.
+  let expiresAt = Math.floor(Date.now() / 1000) + 600;   // fallback: 10 min
+  try {
+    const parts = jwt.split('.');
+    const pad = (s: string) => s + '='.repeat((4 - (s.length % 4)) % 4);
+    const payload = JSON.parse(
+      Buffer.from(pad(parts[1]).replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'),
+    );
+    if (typeof payload.exp === 'number') expiresAt = payload.exp;
+  } catch { /* fall back to default */ }
+
+  return { jwt, expiresAt };
+}
+
+// ----------------------------------------------------------------------------
+// In-memory cache — refresh ~60s before expiry
+// ----------------------------------------------------------------------------
+
+interface CacheEntry {
+  jwt: string;
+  expiresAt: number;
+  apiKey: string;
+  host: string;
+}
+
+/**
+ * Cache is keyed by (apiKey, host). A single shared `cache` slot only holds
+ * the MOST RECENTLY USED entry — common case is one account at a time, so
+ * a single slot is enough. inFlight is a per-key map so a JWT mint for
+ * account A doesn't get returned to a concurrent request for account B.
+ *
+ * Previously `inFlight` was a singleton — if account A's mint was in flight
+ * and a request for account B arrived, B got A's JWT. That's the M1
+ * "concurrent requests after account switch get wrong JWT" bug.
+ */
+let cache: CacheEntry | null = null;
+const inFlight = new Map<string, Promise<MintedUserJwt>>();
+/**
+ * Monotonic epoch counter. Incremented on every `clearCachedUserJwt()`
+ * call so an in-flight mint that started BEFORE the clear can't
+ * repopulate the cache after-the-fact. Without this, a logout that
+ * happened concurrently with a mint would silently get its just-
+ * invalidated JWT cached and served for the next ~24 minutes.
+ */
+let cacheEpoch = 0;
+
+function flightKey(apiKey: string, host: string): string {
+  return `${host}\x1f${apiKey}`;
+}
+
+/**
+ * Get a cached user_jwt or mint a new one. Refreshes when the cached JWT is
+ * within 60s of expiry. Multiple concurrent callers for the SAME (apiKey, host)
+ * share the same in-flight mint; concurrent callers for DIFFERENT keys each
+ * get their own mint.
+ */
+export async function getCachedUserJwt(apiKey: string, host: string = DEFAULT_HOST, signal?: AbortSignal): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+  if (cache && cache.apiKey === apiKey && cache.host === host && cache.expiresAt > now + 60) {
+    return cache.jwt;
+  }
+  const key = flightKey(apiKey, host);
+  const existing = inFlight.get(key);
+  if (existing) return (await existing).jwt;
+  const promise = mintUserJwt(apiKey, host, signal);
+  inFlight.set(key, promise);
+  // Snapshot the epoch BEFORE awaiting the mint. If clearCachedUserJwt()
+  // fires while we're awaiting (logout-during-mint), the epoch changes
+  // and we won't repopulate the cache with the just-invalidated JWT.
+  const epochAtStart = cacheEpoch;
+  try {
+    const minted = await promise;
+    if (cacheEpoch === epochAtStart) {
+      cache = { jwt: minted.jwt, expiresAt: minted.expiresAt, apiKey, host };
+    }
+    return minted.jwt;
+  } finally {
+    inFlight.delete(key);
+  }
+}
+
+/**
+ * Drop the in-memory JWT cache. Call after credential changes (logout,
+ * account switch) so long-running opencode processes don't keep using a
+ * JWT minted from a now-invalid api_key. Also bumps the cache epoch so
+ * any in-flight mint racing with this clear can't repopulate cache
+ * with the stale JWT after-the-fact.
+ */
+export function clearCachedUserJwt(): void {
+  cache = null;
+  inFlight.clear();
+  cacheEpoch++;
+}