Merge pull request #107 from rithulkamesh/main

feat: GitHub Models provider + interactive onboard (keychain-backed)
2026-04-02 20:14:51 +08:00
parent 6b7c0e5339 0a42839475
commit 903a30916a
24 changed files with 1064 additions and 44 deletions
--- a/src/services/api/client.ts
+++ b/src/services/api/client.ts
@@ -154,7 +154,10 @@ export async function getAnthropicClient({
      fetch: resolvedFetch,
    }),
  }
-  if (isEnvTruthy(process.env.CLAUDE_CODE_USE_OPENAI)) {
+  if (
+    isEnvTruthy(process.env.CLAUDE_CODE_USE_OPENAI) ||
+    isEnvTruthy(process.env.CLAUDE_CODE_USE_GITHUB)
+  ) {
    const { createOpenAIShimClient } = await import('./openaiShim.js')
    return createOpenAIShimClient({
      defaultHeaders,
--- a/src/services/api/openaiShim.ts
+++ b/src/services/api/openaiShim.ts
@@ -14,8 +14,15 @@
 *   OPENAI_BASE_URL=http://...        — base URL (default: https://api.openai.com/v1)
 *   OPENAI_MODEL=gpt-4o              — default model override
 *   CODEX_API_KEY / ~/.codex/auth.json — Codex auth for codexplan/codexspark
+ *
+ * GitHub Models (models.github.ai), OpenAI-compatible:
+ *   CLAUDE_CODE_USE_GITHUB=1         — enable GitHub inference (no need for USE_OPENAI)
+ *   GITHUB_TOKEN or GH_TOKEN         — PAT with models access (mapped to Bearer auth)
+ *   OPENAI_MODEL                     — optional; use github:copilot or openai/gpt-4.1 style IDs
 */

+import { isEnvTruthy } from '../../utils/envUtils.js'
+import { hydrateGithubModelsTokenFromSecureStorage } from '../../utils/githubModelsCredentials.js'
 import {
  codexStreamToAnthropic,
  collectCodexCompletedResponse,
@@ -30,6 +37,25 @@ import {
  resolveProviderRequest,
 } from './providerConfig.js'

+const GITHUB_MODELS_DEFAULT_BASE = 'https://models.github.ai/inference'
+const GITHUB_API_VERSION = '2022-11-28'
+const GITHUB_429_MAX_RETRIES = 3
+const GITHUB_429_BASE_DELAY_SEC = 1
+const GITHUB_429_MAX_DELAY_SEC = 32
+
+function isGithubModelsMode(): boolean {
+  return isEnvTruthy(process.env.CLAUDE_CODE_USE_GITHUB)
+}
+
+function formatRetryAfterHint(response: Response): string {
+  const ra = response.headers.get('retry-after')
+  return ra ? ` (Retry-After: ${ra})` : ''
+}
+
+function sleepMs(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
 // ---------------------------------------------------------------------------
 // Types — minimal subset of Anthropic SDK types we need to produce
 // ---------------------------------------------------------------------------
@@ -294,9 +320,7 @@ function normalizeSchemaForOpenAI(
 function convertTools(
  tools: Array<{ name: string; description?: string; input_schema?: Record<string, unknown> }>,
 ): OpenAITool[] {
-  const isGemini =
-    process.env.CLAUDE_CODE_USE_GEMINI === '1' ||
-    process.env.CLAUDE_CODE_USE_GEMINI === 'true'
+  const isGemini = isEnvTruthy(process.env.CLAUDE_CODE_USE_GEMINI)

  return tools
    .filter(t => t.name !== 'ToolSearchTool') // Not relevant for OpenAI
@@ -754,6 +778,12 @@ class OpenAIShimMessages {
      body.stream_options = { include_usage: true }
    }

+    const isGithub = isGithubModelsMode()
+    if (isGithub && body.max_completion_tokens !== undefined) {
+      body.max_tokens = body.max_completion_tokens
+      delete body.max_completion_tokens
+    }
+
    if (params.temperature !== undefined) body.temperature = params.temperature
    if (params.top_p !== undefined) body.top_p = params.top_p

@@ -803,6 +833,11 @@ class OpenAIShimMessages {
      }
    }

+    if (isGithub) {
+      headers.Accept = 'application/vnd.github.v3+json'
+      headers['X-GitHub-Api-Version'] = GITHUB_API_VERSION
+    }
+
    // Build the chat completions URL
    // Azure Cognitive Services / Azure OpenAI require a deployment-specific path
    // and an api-version query parameter.
@@ -825,19 +860,42 @@ class OpenAIShimMessages {
      chatCompletionsUrl = `${request.baseUrl}/chat/completions`
    }

-    const response = await fetch(chatCompletionsUrl, {
-      method: 'POST',
+    const fetchInit = {
+      method: 'POST' as const,
      headers,
      body: JSON.stringify(body),
      signal: options?.signal,
-    })
-
-    if (!response.ok) {
-      const errorBody = await response.text().catch(() => 'unknown error')
-      throw new Error(`OpenAI API error ${response.status}: ${errorBody}`)
    }

-    return response
+    const maxAttempts = isGithub ? GITHUB_429_MAX_RETRIES : 1
+    let response: Response | undefined
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      response = await fetch(chatCompletionsUrl, fetchInit)
+      if (response.ok) {
+        return response
+      }
+      if (
+        isGithub &&
+        response.status === 429 &&
+        attempt < maxAttempts - 1
+      ) {
+        await response.text().catch(() => {})
+        const delaySec = Math.min(
+          GITHUB_429_BASE_DELAY_SEC * 2 ** attempt,
+          GITHUB_429_MAX_DELAY_SEC,
+        )
+        await sleepMs(delaySec * 1000)
+        continue
+      }
+      const errorBody = await response.text().catch(() => 'unknown error')
+      const rateHint =
+        isGithub && response.status === 429 ? formatRetryAfterHint(response) : ''
+      throw new Error(
+        `OpenAI API error ${response.status}: ${errorBody}${rateHint}`,
+      )
+    }
+
+    throw new Error('OpenAI shim: request loop exited unexpectedly')
  }

  private _convertNonStreamingResponse(
@@ -847,7 +905,10 @@ class OpenAIShimMessages {
      choices?: Array<{
        message?: {
          role?: string
-          content?: string | null
+          content?:
+            | string
+            | null
+            | Array<{ type?: string; text?: string }>
          tool_calls?: Array<{
            id: string
            function: { name: string; arguments: string }
@@ -866,8 +927,25 @@ class OpenAIShimMessages {
    const choice = data.choices?.[0]
    const content: Array<Record<string, unknown>> = []

-    if (choice?.message?.content) {
-      content.push({ type: 'text', text: choice.message.content })
+    const rawContent = choice?.message?.content
+    if (typeof rawContent === 'string' && rawContent) {
+      content.push({ type: 'text', text: rawContent })
+    } else if (Array.isArray(rawContent) && rawContent.length > 0) {
+      const parts: string[] = []
+      for (const part of rawContent) {
+        if (
+          part &&
+          typeof part === 'object' &&
+          part.type === 'text' &&
+          typeof part.text === 'string'
+        ) {
+          parts.push(part.text)
+        }
+      }
+      const joined = parts.join('\n')
+      if (joined) {
+        content.push({ type: 'text', text: joined })
+      }
    }

    if (choice?.message?.tool_calls) {
@@ -926,12 +1004,11 @@ export function createOpenAIShimClient(options: {
  maxRetries?: number
  timeout?: number
 }): unknown {
+  hydrateGithubModelsTokenFromSecureStorage()
+
  // When Gemini provider is active, map Gemini env vars to OpenAI-compatible ones
  // so the existing providerConfig.ts infrastructure picks them up correctly.
-  if (
-    process.env.CLAUDE_CODE_USE_GEMINI === '1' ||
-    process.env.CLAUDE_CODE_USE_GEMINI === 'true'
-  ) {
+  if (isEnvTruthy(process.env.CLAUDE_CODE_USE_GEMINI)) {
    process.env.OPENAI_BASE_URL ??=
      process.env.GEMINI_BASE_URL ??
      'https://generativelanguage.googleapis.com/v1beta/openai'
@@ -940,6 +1017,10 @@ export function createOpenAIShimClient(options: {
    if (process.env.GEMINI_MODEL && !process.env.OPENAI_MODEL) {
      process.env.OPENAI_MODEL = process.env.GEMINI_MODEL
    }
+  } else if (isEnvTruthy(process.env.CLAUDE_CODE_USE_GITHUB)) {
+    process.env.OPENAI_BASE_URL ??= GITHUB_MODELS_DEFAULT_BASE
+    process.env.OPENAI_API_KEY ??=
+      process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? ''
  }

  const beta = new OpenAIShimBeta({
--- a/src/services/api/providerConfig.github.test.ts
+++ b/src/services/api/providerConfig.github.test.ts
@@ -0,0 +1,41 @@
+import { afterEach, expect, test } from 'bun:test'
+
+import {
+  DEFAULT_GITHUB_MODELS_API_MODEL,
+  normalizeGithubModelsApiModel,
+  resolveProviderRequest,
+} from './providerConfig.js'
+
+const originalUseGithub = process.env.CLAUDE_CODE_USE_GITHUB
+
+afterEach(() => {
+  if (originalUseGithub === undefined) {
+    delete process.env.CLAUDE_CODE_USE_GITHUB
+  } else {
+    process.env.CLAUDE_CODE_USE_GITHUB = originalUseGithub
+  }
+})
+
+test.each([
+  ['copilot', DEFAULT_GITHUB_MODELS_API_MODEL],
+  ['github:copilot', DEFAULT_GITHUB_MODELS_API_MODEL],
+  ['', DEFAULT_GITHUB_MODELS_API_MODEL],
+  ['github:gpt-4o', 'gpt-4o'],
+  ['gpt-4o', 'gpt-4o'],
+  ['github:copilot?reasoning=high', DEFAULT_GITHUB_MODELS_API_MODEL],
+] as const)('normalizeGithubModelsApiModel(%s) -> %s', (input, expected) => {
+  expect(normalizeGithubModelsApiModel(input)).toBe(expected)
+})
+
+test('resolveProviderRequest applies GitHub normalization when CLAUDE_CODE_USE_GITHUB=1', () => {
+  process.env.CLAUDE_CODE_USE_GITHUB = '1'
+  const r = resolveProviderRequest({ model: 'github:gpt-4o' })
+  expect(r.resolvedModel).toBe('gpt-4o')
+  expect(r.transport).toBe('chat_completions')
+})
+
+test('resolveProviderRequest leaves model unchanged without GitHub flag', () => {
+  delete process.env.CLAUDE_CODE_USE_GITHUB
+  const r = resolveProviderRequest({ model: 'github:gpt-4o' })
+  expect(r.resolvedModel).toBe('github:gpt-4o')
+})
--- a/src/services/api/providerConfig.ts
+++ b/src/services/api/providerConfig.ts
@@ -2,8 +2,12 @@ import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'

+import { isEnvTruthy } from '../../utils/envUtils.js'
+
 export const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com/v1'
 export const DEFAULT_CODEX_BASE_URL = 'https://chatgpt.com/backend-api/codex'
+/** Default GitHub Models API model when user selects copilot / github:copilot */
+export const DEFAULT_GITHUB_MODELS_API_MODEL = 'openai/gpt-4.1'

 const CODEX_ALIAS_MODELS: Record<
  string,
@@ -171,16 +175,31 @@ export function isCodexBaseUrl(baseUrl: string | undefined): boolean {
  }
 }

+/**
+ * Normalize user model string for GitHub Models inference (models.github.ai).
+ * Mirrors runtime devsper `github._normalize_model_id`.
+ */
+export function normalizeGithubModelsApiModel(requestedModel: string): string {
+  const noQuery = requestedModel.split('?', 1)[0] ?? requestedModel
+  const segment =
+    noQuery.includes(':') ? noQuery.split(':', 2)[1]!.trim() : noQuery.trim()
+  if (!segment || segment.toLowerCase() === 'copilot') {
+    return DEFAULT_GITHUB_MODELS_API_MODEL
+  }
+  return segment
+}
+
 export function resolveProviderRequest(options?: {
  model?: string
  baseUrl?: string
  fallbackModel?: string
 }): ResolvedProviderRequest {
+  const isGithubMode = isEnvTruthy(process.env.CLAUDE_CODE_USE_GITHUB)
  const requestedModel =
    options?.model?.trim() ||
    process.env.OPENAI_MODEL?.trim() ||
    options?.fallbackModel?.trim() ||
-    'gpt-4o'
+    (isGithubMode ? 'github:copilot' : 'gpt-4o')
  const descriptor = parseModelDescriptor(requestedModel)
  const rawBaseUrl =
    options?.baseUrl ??
@@ -192,10 +211,16 @@ export function resolveProviderRequest(options?: {
      ? 'codex_responses'
      : 'chat_completions'

+  const resolvedModel =
+    transport === 'chat_completions' &&
+    isEnvTruthy(process.env.CLAUDE_CODE_USE_GITHUB)
+      ? normalizeGithubModelsApiModel(requestedModel)
+      : descriptor.baseModel
+
  return {
    transport,
    requestedModel,
-    resolvedModel: descriptor.baseModel,
+    resolvedModel,
    baseUrl:
      (rawBaseUrl ??
        (transport === 'codex_responses'
--- a/src/services/github/deviceFlow.test.ts
+++ b/src/services/github/deviceFlow.test.ts
@@ -0,0 +1,94 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test'
+
+import {
+  GitHubDeviceFlowError,
+  pollAccessToken,
+  requestDeviceCode,
+} from './deviceFlow.js'
+
+describe('requestDeviceCode', () => {
+  const originalFetch = globalThis.fetch
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  test('parses successful device code response', async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(
+        new Response(
+          JSON.stringify({
+            device_code: 'abc',
+            user_code: 'ABCD-1234',
+            verification_uri: 'https://github.com/login/device',
+            expires_in: 600,
+            interval: 5,
+          }),
+          { status: 200 },
+        ),
+      ),
+    )
+
+    const r = await requestDeviceCode({
+      clientId: 'test-client',
+      fetchImpl: globalThis.fetch,
+    })
+    expect(r.device_code).toBe('abc')
+    expect(r.user_code).toBe('ABCD-1234')
+    expect(r.verification_uri).toBe('https://github.com/login/device')
+    expect(r.expires_in).toBe(600)
+    expect(r.interval).toBe(5)
+  })
+
+  test('throws on HTTP error', async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(new Response('bad', { status: 500 })),
+    )
+    await expect(
+      requestDeviceCode({ clientId: 'x', fetchImpl: globalThis.fetch }),
+    ).rejects.toThrow(GitHubDeviceFlowError)
+  })
+})
+
+describe('pollAccessToken', () => {
+  const originalFetch = globalThis.fetch
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  test('returns token when GitHub responds with access_token immediately', async () => {
+    let calls = 0
+    globalThis.fetch = mock(() => {
+      calls++
+      return Promise.resolve(
+        new Response(JSON.stringify({ access_token: 'tok-xyz' }), {
+          status: 200,
+        }),
+      )
+    })
+
+    const token = await pollAccessToken('dev-code', {
+      clientId: 'cid',
+      fetchImpl: globalThis.fetch,
+    })
+    expect(token).toBe('tok-xyz')
+    expect(calls).toBe(1)
+  })
+
+  test('throws on access_denied', async () => {
+    globalThis.fetch = mock(() =>
+      Promise.resolve(
+        new Response(JSON.stringify({ error: 'access_denied' }), {
+          status: 200,
+        }),
+      ),
+    )
+    await expect(
+      pollAccessToken('dc', {
+        clientId: 'c',
+        fetchImpl: globalThis.fetch,
+      }),
+    ).rejects.toThrow(/denied/)
+  })
+})
--- a/src/services/github/deviceFlow.ts
+++ b/src/services/github/deviceFlow.ts
@@ -0,0 +1,174 @@
+/**
+ * GitHub OAuth device flow for CLI login (https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow).
+ */
+
+import { execFileNoThrow } from '../../utils/execFileNoThrow.js'
+
+export const DEFAULT_GITHUB_DEVICE_FLOW_CLIENT_ID = 'Ov23liXjWSSui6QIahPl'
+
+export const GITHUB_DEVICE_CODE_URL = 'https://github.com/login/device/code'
+export const GITHUB_DEVICE_ACCESS_TOKEN_URL =
+  'https://github.com/login/oauth/access_token'
+
+/** Match runtime devsper github_oauth DEFAULT_SCOPE */
+export const DEFAULT_GITHUB_DEVICE_SCOPE = 'read:user,models:read'
+
+export class GitHubDeviceFlowError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'GitHubDeviceFlowError'
+  }
+}
+
+export type DeviceCodeResult = {
+  device_code: string
+  user_code: string
+  verification_uri: string
+  expires_in: number
+  interval: number
+}
+
+export function getGithubDeviceFlowClientId(): string {
+  return (
+    process.env.GITHUB_DEVICE_FLOW_CLIENT_ID?.trim() ||
+    DEFAULT_GITHUB_DEVICE_FLOW_CLIENT_ID
+  )
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+export async function requestDeviceCode(options?: {
+  clientId?: string
+  scope?: string
+  fetchImpl?: typeof fetch
+}): Promise<DeviceCodeResult> {
+  const clientId = options?.clientId ?? getGithubDeviceFlowClientId()
+  if (!clientId) {
+    throw new GitHubDeviceFlowError(
+      'No OAuth client ID: set GITHUB_DEVICE_FLOW_CLIENT_ID or paste a PAT instead.',
+    )
+  }
+  const fetchFn = options?.fetchImpl ?? fetch
+  const res = await fetchFn(GITHUB_DEVICE_CODE_URL, {
+    method: 'POST',
+    headers: { Accept: 'application/json' },
+    body: new URLSearchParams({
+      client_id: clientId,
+      scope: options?.scope ?? DEFAULT_GITHUB_DEVICE_SCOPE,
+    }),
+  })
+  if (!res.ok) {
+    const text = await res.text().catch(() => '')
+    throw new GitHubDeviceFlowError(
+      `Device code request failed: ${res.status} ${text}`,
+    )
+  }
+  const data = (await res.json()) as Record<string, unknown>
+  const device_code = data.device_code
+  const user_code = data.user_code
+  const verification_uri = data.verification_uri
+  if (
+    typeof device_code !== 'string' ||
+    typeof user_code !== 'string' ||
+    typeof verification_uri !== 'string'
+  ) {
+    throw new GitHubDeviceFlowError('Malformed device code response from GitHub')
+  }
+  return {
+    device_code,
+    user_code,
+    verification_uri,
+    expires_in: typeof data.expires_in === 'number' ? data.expires_in : 900,
+    interval: typeof data.interval === 'number' ? data.interval : 5,
+  }
+}
+
+export type PollOptions = {
+  clientId?: string
+  initialInterval?: number
+  timeoutSeconds?: number
+  fetchImpl?: typeof fetch
+}
+
+export async function pollAccessToken(
+  deviceCode: string,
+  options?: PollOptions,
+): Promise<string> {
+  const clientId = options?.clientId ?? getGithubDeviceFlowClientId()
+  if (!clientId) {
+    throw new GitHubDeviceFlowError('client_id required for polling')
+  }
+  let interval = Math.max(1, options?.initialInterval ?? 5)
+  const timeoutSeconds = options?.timeoutSeconds ?? 900
+  const fetchFn = options?.fetchImpl ?? fetch
+  const start = Date.now()
+
+  while ((Date.now() - start) / 1000 < timeoutSeconds) {
+    const res = await fetchFn(GITHUB_DEVICE_ACCESS_TOKEN_URL, {
+      method: 'POST',
+      headers: { Accept: 'application/json' },
+      body: new URLSearchParams({
+        client_id: clientId,
+        device_code: deviceCode,
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      }),
+    })
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new GitHubDeviceFlowError(
+        `Token request failed: ${res.status} ${text}`,
+      )
+    }
+    const data = (await res.json()) as Record<string, unknown>
+    const err = data.error as string | undefined
+    if (err == null) {
+      const token = data.access_token
+      if (typeof token === 'string' && token) {
+        return token
+      }
+      throw new GitHubDeviceFlowError('No access_token in response')
+    }
+    if (err === 'authorization_pending') {
+      await sleep(interval * 1000)
+      continue
+    }
+    if (err === 'slow_down') {
+      interval =
+        typeof data.interval === 'number' ? data.interval : interval + 5
+      await sleep(interval * 1000)
+      continue
+    }
+    if (err === 'expired_token') {
+      throw new GitHubDeviceFlowError(
+        'Device code expired. Start the login flow again.',
+      )
+    }
+    if (err === 'access_denied') {
+      throw new GitHubDeviceFlowError('Authorization was denied or cancelled.')
+    }
+    throw new GitHubDeviceFlowError(`GitHub OAuth error: ${err}`)
+  }
+  throw new GitHubDeviceFlowError('Timed out waiting for authorization.')
+}
+
+/**
+ * Best-effort open browser / OS handler for the verification URL.
+ */
+export async function openVerificationUri(uri: string): Promise<void> {
+  try {
+    if (process.platform === 'darwin') {
+      await execFileNoThrow('open', [uri], { useCwd: false, timeout: 5000 })
+    } else if (process.platform === 'win32') {
+      await execFileNoThrow('cmd', ['/c', 'start', '', uri], {
+        useCwd: false,
+        timeout: 5000,
+      })
+    } else {
+      await execFileNoThrow('xdg-open', [uri], { useCwd: false, timeout: 5000 })
+    }
+  } catch {
+    // User can open the URL manually
+  }
+}