pi-devin-auth 0.1.0

package/src/oauth/login.ts

@@ -0,0 +1,95 @@
+/**
+ * Drive a browser-based Windsurf sign-in via pi's `OAuthLoginCallbacks`.
+ *
+ * Flow:
+ *   1. Build an Auth0 implicit-grant URL (`response_type=token`) pointing at
+ *      Windsurf's SPA sign-in page with `redirect_uri=show-auth-token`. That
+ *      special redirect tells the SPA to render the resulting access token in
+ *      a `<code>` block on screen instead of redirecting away — the user
+ *      copies it manually.
+ *   2. `callbacks.onAuth({ url })` opens the browser.
+ *   3. `callbacks.onPrompt(...)` collects the pasted token. That pasted value
+ *      IS the Firebase ID token (the `access_token` from the OAuth fragment).
+ *   4. `registerUser(pasted, region)` exchanges it for a long-lived API key.
+ *   5. We wrap the key in `OAuthCredentials` and return it.
+ *
+ * Why manual paste instead of a loopback redirect? pi's `OAuthLoginCallbacks`
+ * surface no way to spin up a local HTTP server or read a redirect — the only
+ * inputs we get back are `onPrompt` (free text) and `onSelect` (pick from a
+ * list). The `show-auth-token` redirect + manual paste is the same trick the
+ * opencode-windsurf-auth CLI uses for headless / SSH environments, and it is
+ * the only shape that fits pi's callback contract.
+ */
+
+import * as crypto from 'crypto';
+import type { OAuthCredentials, OAuthLoginCallbacks } from '@earendil-works/pi-ai';
+import { registerUser } from './register-user.js';
+import { DEFAULT_REGION, type WindsurfRegion } from './types.js';
+
+/** One year in milliseconds — the API key is effectively non-expiring. */
+const ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000;
+
+/**
+ * Build the Auth0 implicit-grant URL for Windsurf's SPA sign-in page.
+ *
+ * Mirrors the params the opencode-windsurf-auth flow sends:
+ *   - `response_type=token`  -> Auth0 returns the access token in the URL
+ *     fragment (implicit grant, no client secret).
+ *   - `redirect_uri=show-auth-token` -> the SPA's special route that renders
+ *     the token on-screen for manual copy instead of bouncing elsewhere.
+ *   - `state` -> random UUID, guards CSRF on the browser round-trip. We do
+ *     not validate it server-side (we never receive the redirect), but
+ *     Auth0 requires it and echoing it back is good hygiene.
+ *   - `prompt=login` -> force a fresh Auth0 login screen even if the user
+ *     has an SSO session, so they can pick a different account.
+ */
+function buildSignInUrl(region: WindsurfRegion): string {
+    const params = new URLSearchParams({
+        response_type: 'token',
+        client_id: region.oauthClientId,
+        redirect_uri: 'show-auth-token',
+        state: crypto.randomUUID(),
+        prompt: 'login',
+    });
+    return `${region.website}/windsurf/signin?${params.toString()}`;
+}
+
+/**
+ * Run the full Windsurf OAuth login through pi's `OAuthLoginCallbacks`.
+ *
+ * The returned `OAuthCredentials.access` is the Windsurf API key (not the
+ * short-lived Firebase token — that is consumed by `registerUser` and
+ * discarded). `refresh` is empty because Windsurf API keys do not expire;
+ * `expires` is set one year out as a soft sentinel, not a hard expiry.
+ *
+ * `WindsurfRegistrationError` thrown by `registerUser` is allowed to
+ * propagate — pi surfaces it to the user.
+ */
+export async function loginDevin(
+    callbacks: OAuthLoginCallbacks,
+    region: WindsurfRegion = DEFAULT_REGION,
+): Promise<OAuthCredentials> {
+    const url = buildSignInUrl(region);
+
+    // Open the browser to the Auth0 sign-in page.
+    callbacks.onAuth({ url });
+
+    // Block until the user pastes the token rendered on the sign-in page.
+    // This is the Firebase ID token (OAuth `access_token` from the fragment).
+    const firebaseIdToken = await callbacks.onPrompt({
+        message: 'Paste the token from the sign-in page:',
+    });
+
+    if (!firebaseIdToken) {
+        throw new Error('No token pasted; cannot complete sign-in.');
+    }
+
+    // Exchange the Firebase token for a long-lived Windsurf API key.
+    const result = await registerUser(firebaseIdToken.trim(), region);
+
+    return {
+        refresh: '',
+        access: result.apiKey,
+        expires: Date.now() + ONE_YEAR_MS,
+    };
+}

package/src/oauth/register-user.ts

@@ -0,0 +1,174 @@
+/**
+ * Exchange a Firebase ID token for a long-lived Windsurf API key.
+ *
+ * This calls the same Connect-RPC endpoint the Windsurf desktop extension uses
+ * after the browser sign-in completes:
+ *
+ *   POST https://register.windsurf.com/exa.seat_management_pb.SeatManagementService/RegisterUser
+ *   Content-Type: application/json
+ *   Body: { "firebase_id_token": "<jwt>" }
+ *
+ * Connect-RPC happily accepts plain JSON over HTTPS (no gRPC framing required),
+ * so we skip @connectrpc/connect entirely and use `fetch`. The response shape
+ * matches `exa.seat_management_pb.RegisterUserResponse`:
+ *
+ *   { api_key, name, api_server_url, redirect_url, team_options[] }
+ *
+ * Endpoint verified live (returns `{code:"unauthenticated",message:"invalid token ..."}`
+ * for a fake token, 200 with the response body for a valid one).
+ */
+
+import type { OAuthLoginResult, WindsurfRegion } from './types.js';
+
+/**
+ * Polyfill for `AbortSignal.any` — composes multiple signals so the result
+ * aborts when ANY input aborts. Built-in in Node ≥20.3 / Bun ≥1.0; we
+ * implement the fallback ourselves so the timeout/caller-signal merge
+ * works on every runtime our `engines` field permits (Node 18+).
+ */
+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;
+}
+
+interface RegisterUserResponseJson {
+  api_key?: string;
+  name?: string;
+  api_server_url?: string;
+  redirect_url?: string;
+  team_options?: unknown[];
+}
+
+interface ConnectErrorJson {
+  code?: string;
+  message?: string;
+}
+
+export class WindsurfRegistrationError extends Error {
+  readonly status: number;
+  readonly connectCode?: string;
+  readonly traceId?: string;
+
+  constructor(message: string, status: number, connectCode?: string, traceId?: string) {
+    super(message);
+    this.name = 'WindsurfRegistrationError';
+    this.status = status;
+    this.connectCode = connectCode;
+    this.traceId = traceId;
+  }
+}
+
+const TRACE_ID_RE = /\(trace ID: ([0-9a-f]+)\)/i;
+
+/**
+ * Exchange the Firebase ID token for a Windsurf API key.
+ *
+ * `firebaseIdToken` is the `access_token` (or `firebase_id_token`) value the
+ * Windsurf sign-in page returns in the OAuth callback URL — we treat it as
+ * opaque.
+ */
+export async function registerUser(
+  firebaseIdToken: string,
+  region: WindsurfRegion,
+  abortSignal?: AbortSignal,
+): Promise<OAuthLoginResult> {
+  if (!firebaseIdToken) {
+    throw new WindsurfRegistrationError('Empty firebase_id_token', 0, 'invalid_argument');
+  }
+
+  const url = `${region.registerApiServerUrl.replace(/\/$/, '')}/exa.seat_management_pb.SeatManagementService/RegisterUser`;
+
+  // 30s internal timeout — RegisterUser responds in ~200ms in steady state.
+  // CLI users on flaky networks need bounded waits or the sign-in command
+  // hangs forever. Compose with the caller's signal via a small polyfill
+  // (`anySignal`) because Node 18 / older Bun lack AbortSignal.any; the
+  // previous fallback `combinedSignal = abortSignal` would drop the
+  // timeout entirely on those runtimes.
+  const timeoutSignal = AbortSignal.timeout(30_000);
+  const combinedSignal: AbortSignal = abortSignal
+    ? anySignal([abortSignal, timeoutSignal])
+    : timeoutSignal;
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      // Connect protocol version header — not strictly required for JSON, but
+      // matches what the official Connect clients send and avoids accidental
+      // routing into a non-Connect HTTP handler.
+      'Connect-Protocol-Version': '1',
+    },
+    body: JSON.stringify({ firebase_id_token: firebaseIdToken }),
+    signal: combinedSignal,
+  });
+
+  const text = await response.text();
+
+  if (!response.ok) {
+    let connectCode: string | undefined;
+    let message = text || `RegisterUser failed with HTTP ${response.status}`;
+    try {
+      const errJson = JSON.parse(text) as ConnectErrorJson;
+      connectCode = errJson.code;
+      if (errJson.message) message = errJson.message;
+    } catch {
+      // non-JSON error body — keep raw text in `message`
+    }
+    const traceMatch = message.match(TRACE_ID_RE);
+    throw new WindsurfRegistrationError(message, response.status, connectCode, traceMatch?.[1]);
+  }
+
+  let parsed: RegisterUserResponseJson;
+  try {
+    parsed = JSON.parse(text) as RegisterUserResponseJson;
+  } catch {
+    throw new WindsurfRegistrationError(
+      `RegisterUser returned 200 but body is not JSON: ${text.slice(0, 200)}`,
+      response.status,
+      'internal',
+    );
+  }
+
+  const apiKey = parsed.api_key;
+  const name = parsed.name;
+  // Empty `api_server_url` is normal for single-tenant accounts — the desktop
+  // extension's `getApiServerUrl` helper falls back to the configured default
+  // when this is empty/missing. We mirror that behavior here.
+  const apiServerUrl = parsed.api_server_url && parsed.api_server_url.length > 0
+    ? parsed.api_server_url
+    : 'https://server.codeium.com';
+
+  if (!apiKey) {
+    throw new WindsurfRegistrationError(
+      'RegisterUser returned 200 but api_key was empty',
+      response.status,
+      'malformed_response',
+    );
+  }
+  if (!name) {
+    throw new WindsurfRegistrationError(
+      'RegisterUser returned 200 but name was empty',
+      response.status,
+      'malformed_response',
+    );
+  }
+
+  return {
+    apiKey,
+    name,
+    apiServerUrl,
+    redirectUrl: parsed.redirect_url,
+  };
+}

package/src/oauth/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared types for the OAuth login flow + persisted credentials.
+ *
+ * Two distinct token shapes appear in this codebase:
+ *
+ *  - `firebaseIdToken` — the short-lived JWT minted by Auth0 / Firebase Auth
+ *    during browser sign-in. Lives in the OAuth callback URL fragment/query.
+ *    Treated as opaque and discarded once exchanged.
+ *
+ *  - `apiKey` — the long-lived credential returned by
+ *    `SeatManagementService.RegisterUser`. Used inside every Cascade RPC's
+ *    `Metadata.api_key` field. Format is provider-defined:
+ *      * Cognition era:  `devin-session-token$<JWT>`
+ *      * Codeium classic: bare UUID v4
+ *      * Older Windsurf:  `sk-ws-01-<...>` / `cog_<...>`
+ *    The plugin treats it as an opaque string — only the cloud cares about format.
+ */
+
+export interface OAuthLoginResult {
+  /** The opaque API key used as `Metadata.api_key` in every Cascade RPC. */
+  apiKey: string;
+  /** Human-readable account name (`Satvik Kapoor`). */
+  name: string;
+  /**
+   * Cloud API server (`https://server.codeium.com`, `https://eu.windsurf.com/_route/api_server`,
+   * `https://windsurf.fedstart.com/_route/api_server`). Driven by the user's
+   * tenant — language_server needs this as `--api_server_url`.
+   */
+  apiServerUrl: string;
+  /** Optional cleanup redirect URL returned by RegisterUser. Informational. */
+  redirectUrl?: string;
+}
+
+export interface PersistedCredentials extends OAuthLoginResult {
+  /** ISO timestamp the credentials were minted at — purely informational. */
+  issuedAt: string;
+  /** Optional tag tracking the OAuth client id used (so a future client rotation can invalidate). */
+  oauthClientId: string;
+  /**
+   * True when these credentials were written as part of the
+   * `opencode auth login` → authorize() flow (so opencode's auth.json is the
+   * authoritative copy and `opencode auth logout windsurf` should mirror-clear
+   * this file). False / absent for credentials written by our standalone
+   * `opencode-windsurf-auth login` CLI; those survive opencode auth state
+   * changes.
+   */
+  syncedViaOpencodeAuth?: boolean;
+}
+
+export interface WindsurfRegion {
+  /** Where to send users for browser sign-in. */
+  website: string;
+  /** Where to POST RegisterUser. */
+  registerApiServerUrl: string;
+  /** Auth0 client id passed in the OAuth URL. */
+  oauthClientId: string;
+}
+
+/**
+ * The single tenant (free / personal) configuration. EU, FedStart, and arbitrary
+ * portal URLs override `website` + `registerApiServerUrl` at runtime when the
+ * user passes `--portal-url` to the login command.
+ */
+export const DEFAULT_REGION: WindsurfRegion = {
+  website: 'https://windsurf.com',
+  registerApiServerUrl: 'https://register.windsurf.com',
+  // From /Applications/Windsurf.app/.../extension.js — the public Windsurf
+  // Auth0 client. If Windsurf rotates this, sign-in will start failing until
+  // we re-extract it.
+  oauthClientId: '3GUryQ7ldAeKEuD2obYnppsnmj58eP5u',
+};

package/src/stream.ts

@@ -0,0 +1,341 @@
+/**
+ * pi `streamSimple` implementation for the Devin/Cognition provider.
+ *
+ * Calls the cloud-direct gRPC streaming layer (`streamChatEvents`) and
+ * translates the resulting `CloudChatEvent` stream into pi's
+ * `AssistantMessageEventStream` events.
+ *
+ * The async-IIFE pattern is the standard pi `streamSimple` shape: the
+ * function returns a `AssistantMessageEventStream` synchronously and drives
+ * the upstream async iterator inside an IIFE, pushing events as they
+ * arrive.
+ */
+import {
+    type Api,
+    type AssistantMessage,
+    type AssistantMessageEventStream,
+    type Context,
+    type Model,
+    type SimpleStreamOptions,
+    calculateCost,
+    createAssistantMessageEventStream,
+} from '@earendil-works/pi-ai';
+import { streamChatEvents, type CloudChatEvent } from './cloud-direct/index.js';
+import { mapContextToChat } from './context-map.js';
+
+/**
+ * Stream a Devin/Cognition chat completion into pi's assistant-message
+ * event stream.
+ *
+ * @param model     pi model descriptor (id, api, provider, cost, ...).
+ * @param context   pi conversation context (systemPrompt, messages, tools).
+ * @param options   streaming options (apiKey, maxTokens, signal, ...).
+ * @returns an {@link AssistantMessageEventStream} that receives events
+ *          as the upstream gRPC stream progresses.
+ */
+export function streamDevin(
+    model: Model<Api>,
+    context: Context,
+    options?: SimpleStreamOptions,
+): AssistantMessageEventStream {
+    const stream = createAssistantMessageEventStream();
+
+    // Drive the upstream async iterator inside an IIFE so the returned
+    // stream is populated asynchronously.
+    void (async () => {
+        const output: AssistantMessage = {
+            role: 'assistant',
+            content: [],
+            api: model.api,
+            provider: model.provider,
+            model: model.id,
+            usage: {
+                input: 0,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                totalTokens: 0,
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            stopReason: 'stop',
+            timestamp: Date.now(),
+        };
+
+        // Block-tracking state. Cognition's wire format has no
+        // `tool_call_end` event, so the end of a tool call is implicit:
+        // a new `tool_call_start` or stream `finish` closes the prior call.
+        let textBlockOpen = false;
+        let thinkingBlockOpen = false;
+        let currentToolCallIndex = -1;
+        let partialJson = '';
+        let currentToolCallId = '';
+        let currentToolCallName = '';
+
+        try {
+            const apiKey = options?.apiKey;
+            if (!apiKey) throw new Error('No Devin API key. Run /login devin');
+
+            const { messages, tools } = mapContextToChat(context);
+            stream.push({ type: 'start', partial: output });
+
+            for await (const ev of streamChatEvents({
+                apiKey,
+                modelUid: model.id,
+                messages,
+                tools: tools.length > 0 ? tools : undefined,
+                signal: options?.signal,
+                completionOpts: {
+                    maxOutputTokens: options?.maxTokens,
+                },
+            })) {
+                handleEvent(ev);
+            }
+
+            // Safety: close any still-open blocks at stream end.
+            closeTextBlock();
+            closeThinkingBlock();
+            if (currentToolCallIndex >= 0) {
+                closeToolCall(
+                    stream,
+                    output,
+                    currentToolCallIndex,
+                    partialJson,
+                    currentToolCallId,
+                    currentToolCallName,
+                );
+                currentToolCallIndex = -1;
+            }
+
+            stream.push({
+                type: 'done',
+                reason: output.stopReason as 'stop' | 'length' | 'toolUse',
+                message: output,
+            });
+            stream.end();
+        } catch (error) {
+            output.stopReason = options?.signal?.aborted ? 'aborted' : 'error';
+            output.errorMessage = error instanceof Error ? error.message : String(error);
+            stream.push({
+                type: 'error',
+                reason: output.stopReason as 'aborted' | 'error',
+                error: output,
+            });
+            stream.end();
+        }
+
+        /**
+         * Dispatch a single {@link CloudChatEvent} to the appropriate
+         * pi event(s), mutating `output` and the block-tracking state.
+         */
+        function handleEvent(ev: CloudChatEvent): void {
+            switch (ev.kind) {
+                case 'text': {
+                    // A text delta ends any open thinking block.
+                    closeThinkingBlock();
+                    if (!textBlockOpen) {
+                        output.content.push({ type: 'text', text: '' });
+                        stream.push({
+                            type: 'text_start',
+                            contentIndex: output.content.length - 1,
+                            partial: output,
+                        });
+                        textBlockOpen = true;
+                    }
+                    const idx = output.content.length - 1;
+                    const block = output.content[idx];
+                    if (block.type === 'text') {
+                        block.text += ev.text;
+                        stream.push({
+                            type: 'text_delta',
+                            contentIndex: idx,
+                            delta: ev.text,
+                            partial: output,
+                        });
+                    }
+                    break;
+                }
+
+                case 'reasoning': {
+                    // A reasoning delta ends any open text block.
+                    closeTextBlock();
+                    if (!thinkingBlockOpen) {
+                        output.content.push({ type: 'thinking', thinking: '' });
+                        stream.push({
+                            type: 'thinking_start',
+                            contentIndex: output.content.length - 1,
+                            partial: output,
+                        });
+                        thinkingBlockOpen = true;
+                    }
+                    const idx = output.content.length - 1;
+                    const block = output.content[idx];
+                    if (block.type === 'thinking') {
+                        block.thinking += ev.text;
+                        stream.push({
+                            type: 'thinking_delta',
+                            contentIndex: idx,
+                            delta: ev.text,
+                            partial: output,
+                        });
+                    }
+                    break;
+                }
+
+                case 'tool_call_start': {
+                    // A new tool call ends any open text/thinking block,
+                    // and implicitly closes the previous tool call.
+                    closeTextBlock();
+                    closeThinkingBlock();
+                    if (currentToolCallIndex >= 0) {
+                        closeToolCall(
+                            stream,
+                            output,
+                            currentToolCallIndex,
+                            partialJson,
+                            currentToolCallId,
+                            currentToolCallName,
+                        );
+                    }
+                    currentToolCallId = ev.id;
+                    currentToolCallName = ev.name;
+                    partialJson = '';
+                    output.content.push({
+                        type: 'toolCall',
+                        id: ev.id,
+                        name: ev.name,
+                        arguments: {},
+                    });
+                    currentToolCallIndex = output.content.length - 1;
+                    stream.push({
+                        type: 'toolcall_start',
+                        contentIndex: currentToolCallIndex,
+                        partial: output,
+                    });
+                    break;
+                }
+
+                case 'tool_call_args': {
+                    // Defensive: args without a preceding start should not
+                    // happen on Cognition's wire format — ignore them.
+                    if (currentToolCallIndex < 0) break;
+                    partialJson += ev.argsDelta;
+                    const block = output.content[currentToolCallIndex];
+                    if (block.type === 'toolCall') {
+                        try {
+                            block.arguments = JSON.parse(partialJson);
+                        } catch {
+                            // Incomplete JSON — keep accumulating deltas.
+                        }
+                    }
+                    stream.push({
+                        type: 'toolcall_delta',
+                        contentIndex: currentToolCallIndex,
+                        delta: ev.argsDelta,
+                        partial: output,
+                    });
+                    break;
+                }
+
+                case 'finish': {
+                    closeTextBlock();
+                    closeThinkingBlock();
+                    if (currentToolCallIndex >= 0) {
+                        closeToolCall(
+                            stream,
+                            output,
+                            currentToolCallIndex,
+                            partialJson,
+                            currentToolCallId,
+                            currentToolCallName,
+                        );
+                        currentToolCallIndex = -1;
+                    }
+                    output.stopReason =
+                        ev.reason === 'tool_calls'
+                            ? 'toolUse'
+                            : ev.reason === 'length'
+                              ? 'length'
+                              : 'stop';
+                    break;
+                }
+
+                case 'usage': {
+                    output.usage.input = ev.promptTokens ?? 0;
+                    output.usage.output = ev.completionTokens ?? 0;
+                    output.usage.cacheRead = ev.cachedInputTokens ?? 0;
+                    output.usage.cacheWrite = ev.cacheCreationInputTokens ?? 0;
+                    output.usage.totalTokens =
+                        ev.totalTokens ?? output.usage.input + output.usage.output;
+                    // calculateCost mutates output.usage.cost in place.
+                    calculateCost(model, output.usage);
+                    break;
+                }
+            }
+        }
+
+        /** Close the open text block, if any, emitting `text_end`. */
+        function closeTextBlock(): void {
+            if (!textBlockOpen) return;
+            const idx = output.content.length - 1;
+            const block = output.content[idx];
+            if (block.type === 'text') {
+                stream.push({
+                    type: 'text_end',
+                    contentIndex: idx,
+                    content: block.text,
+                    partial: output,
+                });
+            }
+            textBlockOpen = false;
+        }
+
+        /** Close the open thinking block, if any, emitting `thinking_end`. */
+        function closeThinkingBlock(): void {
+            if (!thinkingBlockOpen) return;
+            const idx = output.content.length - 1;
+            const block = output.content[idx];
+            if (block.type === 'thinking') {
+                stream.push({
+                    type: 'thinking_end',
+                    contentIndex: idx,
+                    content: block.thinking,
+                    partial: output,
+                });
+            }
+            thinkingBlockOpen = false;
+        }
+    })();
+
+    return stream;
+}
+
+/**
+ * Close a tool-call block: attempt a final JSON parse of the accumulated
+ * args delta and emit `toolcall_end` with the resolved {@link ToolCall}.
+ *
+ * Defined at module scope so it is hoisted and usable from the IIFE
+ * closure without forward-reference concerns.
+ */
+function closeToolCall(
+    stream: AssistantMessageEventStream,
+    output: AssistantMessage,
+    index: number,
+    partialJson: string,
+    id: string,
+    name: string,
+): void {
+    const block = output.content[index];
+    if (block.type !== 'toolCall') return;
+    // One last parse attempt in case the final delta completed the JSON.
+    try {
+        block.arguments = JSON.parse(partialJson);
+    } catch {
+        // Leave arguments as the last successfully-parsed value (or `{}`).
+    }
+    stream.push({
+        type: 'toolcall_end',
+        contentIndex: index,
+        toolCall: { type: 'toolCall', id, name, arguments: block.arguments },
+        partial: output,
+    });
+}