pi-devin-auth 0.1.0

package/src/cloud-direct/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Public surface of the cloud-direct module.
+ *
+ * Usage:
+ *   import { streamChat } from './cloud-direct/index.js';
+ *
+ *   for await (const delta of streamChat({
+ *     apiKey: creds.apiKey,
+ *     apiServerUrl: creds.apiServerUrl,
+ *     modelUid: 'swe-1-6',
+ *     messages: [{ role: 'user', content: 'hi' }],
+ *   })) {
+ *     process.stdout.write(delta);
+ *   }
+ */
+
+export {
+  streamChat,
+  streamChatEvents,
+  allocateCascadeId,
+  CloudChatError,
+  type CloudChatRequest,
+  type ChatHistoryItem,
+  type CloudChatEvent,
+  type ToolDef,
+} from './chat.js';
+
+export {
+  mintUserJwt,
+  getCachedUserJwt,
+  clearCachedUserJwt,
+  CloudAuthError,
+} from './auth.js';
+
+export {
+  getCachedCatalog,
+  clearCachedCatalog,
+  ModelNotAvailableError,
+  type ModelCatalogEntry,
+} from './catalog.js';

package/src/cloud-direct/metadata.ts

@@ -0,0 +1,78 @@
+/**
+ * `exa.codeium_common_pb.Metadata` proto builder.
+ *
+ * Field numbers come from src/plugin/discovery.ts (which reads the bundled
+ * extension.js for live numbers). For cloud-direct we hard-code the canonical
+ * set of fields the LS always populates — the IDE-extracted dynamic numbers
+ * would help if Windsurf renumbers, but we don't have a way to refresh those
+ * without the bundled extension.js path being present.
+ *
+ * Captured from real LS upstream traffic via mitm reverse-proxy. See
+ * docs/CLOUD_DIRECT.md → "The exact captured request body (annotated)".
+ */
+
+import {
+  encodeMessage,
+  encodeString,
+  encodeTimestampBody,
+  encodeVarintField,
+} from './wire.js';
+
+/**
+ * extension_version + ide_version sent to the cloud. MUST be a string the
+ * cloud recognizes as a real Windsurf release — Cognition's API silently
+ * rejects unknown version strings with `failed_precondition: "an internal
+ * error occurred"`. We previously tried pulling our package.json version
+ * (e.g. "0.3.0") and the cloud rejected every request. Stays pinned to a
+ * known-good "2.0.0" until/unless someone explicitly overrides via
+ * `MetadataInput.windsurfVersion`.
+ */
+const WINDSURF_VERSION_STRING = '2.0.0';
+
+export interface MetadataInput {
+  /** Persistent api_key from OAuth (`devin-session-token$<JWT>`). */
+  apiKey: string;
+  /** Fresh user_jwt from GetUserJwt — required for chat methods. */
+  userJwt?: string;
+  /** UUID — one per opencode session is fine. */
+  sessionId: string;
+  /** Monotonic, milliseconds since epoch. */
+  requestId: bigint;
+  /** UUID — one per RPC call. */
+  triggerId: string;
+  /** Optional override for the version string. Cosmetic. */
+  windsurfVersion?: string;
+  /** Optional override for the host OS string. */
+  osName?: string;
+}
+
+function osString(): string {
+  switch (process.platform) {
+    case 'darwin': return 'darwin';
+    case 'linux': return 'linux';
+    case 'win32': return 'windows';
+    default: return String(process.platform);
+  }
+}
+
+export function buildMetadata(input: MetadataInput): Buffer {
+  const version = input.windsurfVersion ?? WINDSURF_VERSION_STRING;
+  const os = input.osName ?? osString();
+  const parts: Buffer[] = [
+    encodeString(1, 'windsurf'),                     // ide_name
+    encodeString(2, version),                         // extension_version
+    encodeString(3, input.apiKey),                    // api_key
+    encodeString(4, 'en'),                            // locale
+    encodeString(5, os),                              // os
+    encodeString(7, version),                         // ide_version
+    encodeVarintField(9, input.requestId),            // request_id (uint64 monotonic)
+    encodeString(10, input.sessionId),                // session_id
+    encodeString(12, 'windsurf'),                     // extension_name
+    encodeMessage(16, encodeTimestampBody()),         // ls_timestamp (google.protobuf.Timestamp)
+    encodeString(25, input.triggerId),                // trigger_id
+    encodeString(26, 'Unset'),                        // plan_name
+    encodeString(28, 'windsurf'),                     // ide_type
+  ];
+  if (input.userJwt) parts.push(encodeString(21, input.userJwt));   // user_jwt
+  return Buffer.concat(parts);
+}

package/src/cloud-direct/wire.ts

@@ -0,0 +1,202 @@
+/**
+ * Manual protobuf + Connect-RPC streaming envelope helpers.
+ *
+ * Connect-RPC streaming wire format (HTTPS POST body):
+ *   ┌─────────────┬────────────────┬──────────────┐
+ *   │ flags 1byte │ length 4B BE   │   payload    │
+ *   └─────────────┴────────────────┴──────────────┘
+ *   flags bit 0x01 = payload is gzip-compressed
+ *   flags bit 0x02 = end-of-stream (trailer frame — JSON {error} or empty {})
+ *
+ * All `Get*` methods on `exa.api_server_pb.ApiServerService` that the
+ * language_server calls upstream use this format, content-type
+ * `application/connect+proto`, with `Connect-Protocol-Version: 1`.
+ *
+ * Kept tiny and dependency-free — same philosophy as src/plugin/protobuf.ts.
+ */
+
+import * as zlib from 'zlib';
+
+// ----------------------------------------------------------------------------
+// Proto wire encode
+// ----------------------------------------------------------------------------
+
+export function encodeVarint(value: number | bigint): Buffer {
+  const v0 = BigInt(value);
+  // Reject negatives at the boundary. Proto3 spec encodes signed types as
+  // 10-byte sign-extended varints; we don't support that here and the
+  // current call sites never need it (tags, lengths, request ids — all
+  // strictly positive). The old loop body would have terminated with
+  // `Number(-1n)` = -1, producing a malformed single 0xFF byte that the
+  // server would misparse silently. Throw instead so future regressions
+  // surface immediately.
+  if (v0 < 0n) {
+    throw new RangeError(`encodeVarint: negative input not supported (got ${value})`);
+  }
+  const bytes: number[] = [];
+  let v = v0;
+  while (v > 127n) {
+    bytes.push(Number(v & 0x7fn) | 0x80);
+    v >>= 7n;
+  }
+  bytes.push(Number(v));
+  return Buffer.from(bytes);
+}
+
+export function encodeTag(fieldNum: number, wire: number): Buffer {
+  return encodeVarint((fieldNum << 3) | wire);
+}
+
+export function encodeString(fieldNum: number, s: string): Buffer {
+  const buf = Buffer.from(s, 'utf8');
+  return Buffer.concat([encodeTag(fieldNum, 2), encodeVarint(buf.length), buf]);
+}
+
+export function encodeMessage(fieldNum: number, body: Buffer): Buffer {
+  return Buffer.concat([encodeTag(fieldNum, 2), encodeVarint(body.length), body]);
+}
+
+export function encodeVarintField(fieldNum: number, v: number | bigint): Buffer {
+  return Buffer.concat([encodeTag(fieldNum, 0), encodeVarint(v)]);
+}
+
+export function encodeFixed64Field(fieldNum: number, v: number): Buffer {
+  const b = Buffer.alloc(8);
+  b.writeDoubleLE(v, 0);
+  return Buffer.concat([encodeTag(fieldNum, 1), b]);
+}
+
+export function encodeTimestampBody(): Buffer {
+  const now = Date.now();
+  const seconds = Math.floor(now / 1000);
+  const nanos = (now % 1000) * 1_000_000;
+  return Buffer.concat([
+    encodeVarintField(1, seconds),
+    nanos > 0 ? encodeVarintField(2, nanos) : Buffer.alloc(0),
+  ]);
+}
+
+// ----------------------------------------------------------------------------
+// Proto wire decode
+// ----------------------------------------------------------------------------
+
+export function decodeVarint(buf: Buffer, offset: number): [bigint, number] {
+  let res = 0n;
+  let shift = 0n;
+  let i = offset;
+  while (i < buf.length) {
+    const b = buf[i++];
+    res |= BigInt(b & 0x7f) << shift;
+    if (!(b & 0x80)) return [res, i];
+    shift += 7n;
+  }
+  throw new Error('truncated varint');
+}
+
+export interface ProtoField {
+  num: number;
+  wire: number;
+  /** varint → bigint, fixed → 8/4 byte Buffer, length-delim → payload Buffer. */
+  value: bigint | Buffer;
+}
+
+export function* iterFields(buf: Buffer): Generator<ProtoField> {
+  let i = 0;
+  while (i < buf.length) {
+    const [tagBig, ai] = decodeVarint(buf, i);
+    i = ai;
+    const tag = Number(tagBig);
+    const num = tag >> 3;
+    const wire = tag & 0x7;
+    if (wire === 0) {
+      const [v, bi] = decodeVarint(buf, i);
+      i = bi;
+      yield { num, wire, value: v };
+    } else if (wire === 1) {
+      // Bounds-check: a truncated frame mustn't yield a short fixed64 slice
+      // that downstream readers treat as a full 8-byte value. Stop iterating
+      // cleanly instead.
+      if (i + 8 > buf.length) return;
+      yield { num, wire, value: buf.slice(i, i + 8) };
+      i += 8;
+    } else if (wire === 2) {
+      const [n, ci] = decodeVarint(buf, i);
+      i = ci;
+      const len = Number(n);
+      // Bounds-check: when the declared length runs past the buffer, the
+      // frame is corrupt or truncated. Returning short-buffered slices to
+      // downstream parsers used to misparse silently (M12).
+      if (len < 0 || i + len > buf.length) return;
+      yield { num, wire, value: buf.slice(i, i + len) };
+      i += len;
+    } else if (wire === 5) {
+      if (i + 4 > buf.length) return;
+      yield { num, wire, value: buf.slice(i, i + 4) };
+      i += 4;
+    } else if (wire === 3 || wire === 4) {
+      // Wire types 3 (start group) and 4 (end group) are deprecated in
+      // proto3 but show up in some Codeium server-generated messages. They
+      // carry no length info; the safe behavior is to stop iterating
+      // gracefully rather than tear down the whole frame parse.
+      return;
+    } else {
+      // Unknown wire type — bail rather than misalign.
+      return;
+    }
+  }
+}
+
+// ----------------------------------------------------------------------------
+// Connect-streaming envelope
+// ----------------------------------------------------------------------------
+
+/**
+ * Wrap `body` (a serialized proto message) in a Connect-streaming envelope.
+ * If `compress` is true, gzip the payload and set the 0x01 flag.
+ */
+export function frameConnectStream(body: Buffer, compress = true): Buffer {
+  let payload = body;
+  let flags = 0;
+  if (compress) {
+    payload = zlib.gzipSync(body);
+    flags |= 0x01;
+  }
+  const header = Buffer.alloc(5);
+  header[0] = flags;
+  header.writeUInt32BE(payload.length, 1);
+  return Buffer.concat([header, payload]);
+}
+
+export interface ConnectFrame {
+  flags: number;
+  /** Decompressed payload (gzip handled here if flags & 0x01). */
+  payload: Buffer;
+  /** Frame is the trailer (end-of-stream). */
+  eos: boolean;
+}
+
+/**
+ * Parse all Connect-streaming frames out of a response body.
+ *
+ * Returns array of decoded frames. Each frame's payload is already gzip-decoded
+ * if the compression flag was set.
+ */
+export function parseConnectFrames(buf: Buffer): ConnectFrame[] {
+  const out: ConnectFrame[] = [];
+  let i = 0;
+  while (i + 5 <= buf.length) {
+    const flags = buf[i];
+    const len = buf.readUInt32BE(i + 1);
+    if (i + 5 + len > buf.length) break;
+    let payload = buf.slice(i + 5, i + 5 + len);
+    if (flags & 0x01) {
+      // Compressed frame. If gunzip fails the frame is genuinely corrupt
+      // — surfacing as a thrown error beats parsing raw gzip bytes as proto
+      // (which previously produced misleading "yielded bad wire type" downstream).
+      payload = zlib.gunzipSync(payload);
+    }
+    out.push({ flags, payload, eos: (flags & 0x02) !== 0 });
+    i += 5 + len;
+  }
+  return out;
+}

package/src/context-map.ts

@@ -0,0 +1,170 @@
+/**
+ * Pure mapping module that converts pi's conversation model
+ * (`Message[]`, `Tool[]`, `systemPrompt`) into the `ChatHistoryItem[]` +
+ * `ToolDef[]` shapes that the cloud-direct gRPC layer expects.
+ *
+ * No side effects, no I/O — trivially unit-testable.
+ */
+import type { Context, Message, Tool } from '@earendil-works/pi-ai';
+import type { ChatHistoryItem, ContentPart, ToolDef } from './cloud-direct/chat.js';
+
+/** Result of mapping a pi {@link Context} into cloud-direct shapes. */
+export interface MappedChat {
+    messages: ChatHistoryItem[];
+    tools: ToolDef[];
+}
+
+/** pi content-part shapes we care about for mapping. */
+interface TextContent {
+    type: 'text';
+    text: string;
+}
+interface ImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+}
+interface ThinkingContent {
+    type: 'thinking';
+    thinking: string;
+}
+interface ToolCallContent {
+    type: 'toolCall';
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+
+/** Discriminated union of assistant content parts. */
+type AssistantContentPart = TextContent | ThinkingContent | ToolCallContent;
+
+/** User/toolResult content parts (no thinking, no toolCall). */
+type UserContentPart = TextContent | ImageContent;
+
+/**
+ * Map pi user/toolResult content (string or array of text/image parts)
+ * into the cloud-direct `ContentPart[]` form. String content is passed
+ * through as-is (ChatHistoryItem.content accepts the string shorthand).
+ */
+function mapContent(
+    content: string | UserContentPart[],
+): string | ContentPart[] {
+    if (typeof content === 'string') return content;
+    const out: ContentPart[] = [];
+    for (const part of content) {
+        if (part.type === 'text') {
+            out.push({ type: 'text', text: part.text });
+        } else if (part.type === 'image') {
+            out.push({
+                type: 'image',
+                mimeType: part.mimeType,
+                base64Data: part.data,
+            });
+        }
+        // Unknown part types are skipped.
+    }
+    return out;
+}
+
+/**
+ * Extract visible text from an assistant message's content array.
+ * Joins all `TextContent` entries with `\n`. `ThinkingContent` and
+ * `ToolCall` entries are skipped — thinking is internal to the model
+ * and tool calls are surfaced separately via {@link extractToolCalls}.
+ */
+function extractText(content: AssistantContentPart[]): string {
+    const texts: string[] = [];
+    for (const part of content) {
+        if (part.type === 'text') texts.push(part.text);
+    }
+    return texts.join('\n');
+}
+
+/**
+ * Extract tool calls from an assistant message's content array into the
+ * cloud-direct `tool_calls` shape. `arguments` is serialized to a JSON
+ * string (the cloud proto expects `arguments_json`). Returns `undefined`
+ * when there are no tool calls so the `tool_calls` field stays absent on
+ * the resulting {@link ChatHistoryItem}.
+ */
+function extractToolCalls(
+    content: AssistantContentPart[],
+): Array<{ id: string; name: string; arguments: string }> | undefined {
+    const calls: Array<{ id: string; name: string; arguments: string }> = [];
+    for (const part of content) {
+        if (part.type === 'toolCall') {
+            calls.push({
+                id: part.id,
+                name: part.name,
+                arguments: JSON.stringify(part.arguments),
+            });
+        }
+    }
+    return calls.length > 0 ? calls : undefined;
+}
+
+/**
+ * Map a single pi {@link Message} into a cloud-direct {@link ChatHistoryItem}.
+ *
+ * - `UserMessage`        -> `{ role: 'user', content: mapContent(...) }`
+ * - `AssistantMessage`   -> `{ role: 'assistant', content: extractText(...),
+ *                              tool_calls: extractToolCalls(...) }`
+ * - `ToolResultMessage`  -> `{ role: 'tool', content: mapContent(...),
+ *                              tool_call_id: msg.toolCallId }`
+ */
+function mapMessage(msg: Message): ChatHistoryItem {
+    if (msg.role === 'user') {
+        return {
+            role: 'user',
+            content: mapContent(msg.content as string | UserContentPart[]),
+        };
+    }
+    if (msg.role === 'assistant') {
+        const parts = msg.content as AssistantContentPart[];
+        const toolCalls = extractToolCalls(parts);
+        const item: ChatHistoryItem = {
+            role: 'assistant',
+            content: extractText(parts),
+        };
+        if (toolCalls !== undefined) item.tool_calls = toolCalls;
+        return item;
+    }
+    // role === 'toolResult'
+    return {
+        role: 'tool',
+        content: mapContent(msg.content as UserContentPart[]),
+        tool_call_id: msg.toolCallId,
+    };
+}
+
+/**
+ * Convert a pi {@link Context} (systemPrompt + messages + tools) into the
+ * `ChatHistoryItem[]` + `ToolDef[]` shapes consumed by the cloud-direct
+ * gRPC chat layer.
+ *
+ * If `context.systemPrompt` is present it is prepended as a `system`
+ * message; cloud-direct's `collapseSystemIntoUser` will inline it into
+ * the next user turn downstream — we just pass it through here.
+ */
+export function mapContextToChat(context: Context): MappedChat {
+    const messages: ChatHistoryItem[] = [];
+
+    if (context.systemPrompt) {
+        messages.push({ role: 'system', content: context.systemPrompt });
+    }
+
+    for (const msg of context.messages) {
+        messages.push(mapMessage(msg));
+    }
+
+    const tools: ToolDef[] = (context.tools ?? []).map(
+        (tool: Tool): ToolDef => ({
+            name: tool.name,
+            description: tool.description,
+            // tool.parameters is a TSchema (JSON Schema object) — pass through.
+            parameters: tool.parameters as unknown,
+        }),
+    );
+
+    return { messages, tools };
+}

package/src/models.ts

@@ -0,0 +1,135 @@
+/**
+ * Resolve the model list for the Devin provider.
+ *
+ * Fetches the per-account catalog from Cognition's gRPC
+ * `GetCascadeModelConfigs` (via {@link getCachedCatalog}) and maps it to
+ * pi's {@link ProviderModelConfig} shape. When the fetch fails (offline,
+ * auth error, transient outage) or the catalog comes back empty, we hand
+ * back {@link FALLBACK_MODELS} so the extension can still show a model
+ * picker before login.
+ *
+ * The catalog only carries `modelUid`, `label`, and `disabled` — it does
+ * NOT include context window, max output tokens, or reasoning capability.
+ * For known popular models we override those fields from
+ * {@link MODEL_OVERRIDES}; unknown UIDs get conservative defaults from
+ * the `DEFAULT_*` constants below.
+ */
+
+import type { ProviderModelConfig } from '@earendil-works/pi-coding-agent';
+import { getCachedCatalog } from './cloud-direct/catalog.js';
+
+/** Default Cognition/Codeium host. */
+const DEFAULT_HOST = 'https://server.codeium.com';
+
+/**
+ * Static fallback list used when the catalog is null or empty (offline,
+ * auth error, pre-login). All free for now — pricing TBD.
+ */
+export const FALLBACK_MODELS: ProviderModelConfig[] = [
+  {
+    id: 'swe-1-6',
+    name: 'SWE 1.6',
+    reasoning: true,
+    input: ['text', 'image'],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'swe-1-6-slow',
+    name: 'SWE 1.6 (Slow)',
+    reasoning: true,
+    input: ['text', 'image'],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 128000,
+  },
+  {
+    id: 'kimi-k2-6',
+    name: 'Kimi K2.6',
+    reasoning: true,
+    input: ['text', 'image'],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 256000,
+    maxTokens: 128000,
+  },
+];
+
+/** Per-model metadata override. All fields optional; missing ones use defaults. */
+interface ModelOverride {
+  contextWindow?: number;
+  maxTokens?: number;
+  reasoning?: boolean;
+  input?: ('text' | 'image')[];
+}
+
+/**
+ * Known-model override table. Cognition's catalog only returns
+ * `modelUid`/`label`/`disabled`, so for UIDs we recognise we supply
+ * accurate context window, max output tokens, reasoning flag, and input
+ * modalities. UIDs not in this map get the `DEFAULT_*` constants.
+ */
+const MODEL_OVERRIDES: Map<string, ModelOverride> = new Map([
+  // SWE models
+  ['swe-1-6', { contextWindow: 256000, maxTokens: 128000, reasoning: true, input: ['text', 'image'] }],
+  ['swe-1-6-slow', { contextWindow: 256000, maxTokens: 128000, reasoning: true, input: ['text', 'image'] }],
+  // Claude family
+  ['claude-opus-4-7-medium', { contextWindow: 200000, maxTokens: 128000, reasoning: true, input: ['text', 'image'] }],
+  ['claude-opus-4-7', { contextWindow: 200000, maxTokens: 128000, reasoning: true, input: ['text', 'image'] }],
+  ['claude-sonnet-4-6', { contextWindow: 200000, maxTokens: 64000, reasoning: true, input: ['text', 'image'] }],
+  ['claude-sonnet-4-5', { contextWindow: 200000, maxTokens: 16384, reasoning: true, input: ['text', 'image'] }],
+  // GPT family
+  ['gpt-5-5', { contextWindow: 272000, maxTokens: 128000, reasoning: true, input: ['text', 'image'] }],
+  ['gpt-5', { contextWindow: 128000, maxTokens: 16384, reasoning: true, input: ['text', 'image'] }],
+  // Gemini
+  ['gemini-3-0-pro', { contextWindow: 1000000, maxTokens: 65536, reasoning: true, input: ['text', 'image'] }],
+  // Kimi
+  ['kimi-k2-6', { contextWindow: 256000, maxTokens: 128000, reasoning: true, input: ['text', 'image'] }],
+]);
+
+/** Conservative defaults for catalog UIDs not in the override table. */
+const DEFAULT_CONTEXT_WINDOW = 256000;
+const DEFAULT_MAX_TOKENS = 128000;
+const DEFAULT_REASONING = true;
+const DEFAULT_INPUT: ('text' | 'image')[] = ['text', 'image'];
+
+/**
+ * Resolve the Devin/Cognition model list for `(apiKey, host)`.
+ *
+ * Flow:
+ *   1. Fetch the per-account catalog via {@link getCachedCatalog}. It
+ *      already returns `null` on failure; the extra `.catch(() => null)`
+ *      is defense in depth for unexpected throws.
+ *   2. If the catalog is null or empty, return {@link FALLBACK_MODELS} so
+ *      the extension can still render a picker pre-login / offline.
+ *   3. Otherwise map every non-disabled catalog entry to a
+ *      {@link ProviderModelConfig}, applying per-model overrides for
+ *      known UIDs and conservative defaults for the rest.
+ *
+ * All costs are 0 for now (free tier / pricing TBD).
+ */
+export async function resolveModels(
+  apiKey: string,
+  host: string = DEFAULT_HOST,
+): Promise<ProviderModelConfig[]> {
+  const catalog = await getCachedCatalog(apiKey, host).catch(() => null);
+
+  if (!catalog || catalog.byUid.size === 0) {
+    return FALLBACK_MODELS;
+  }
+
+  return [...catalog.byUid.values()]
+    .filter((entry) => !entry.disabled)
+    .map((entry) => {
+      const override = MODEL_OVERRIDES.get(entry.modelUid);
+      return {
+        id: entry.modelUid,
+        name: entry.label || entry.modelUid,
+        reasoning: override?.reasoning ?? DEFAULT_REASONING,
+        input: override?.input ?? DEFAULT_INPUT,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: override?.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+        maxTokens: override?.maxTokens ?? DEFAULT_MAX_TOKENS,
+      };
+    });
+}