[ENHANCEMENT] Improve provider ingestion onboarding and add OpenAI OAuth

[mojomast]

Problem (one or two sentences)

New users have too much setup friction when connecting providers, and OpenAI setup currently relies on manual API key handling. This causes drop-off during onboarding and increases misconfiguration issues.

Context (who is affected and when)

This most affects first-time users configuring providers in Roo Code, especially when trying to get started quickly from a fresh install. It is also common for users who want OpenAI access but prefer account-based sign-in over key management.

Desired behavior (conceptual, not technical)

Provider setup should feel guided and reliable, with clear onboarding steps, sensible defaults, and immediate feedback that a provider is ready to use. OpenAI should support OAuth sign-in so users can connect securely without manually creating/pasting API keys.

Constraints / preferences (optional)

• Keep setup fast for first-time users
• Make failures actionable and easy to recover from
• Preserve explicit user consent and clear auth state visibility
• Avoid cluttering advanced settings for basic onboarding

Acceptance criteria (optional)

Given a new user opening provider setup
When they complete onboarding
Then they can connect at least one provider end-to-end with clear success/failure status
And onboarding clearly distinguishes recommended defaults vs advanced options
And OpenAI can be connected via OAuth flow without manual API key entry
But existing API-key-based OpenAI configuration continues to work

Proposed approach (optional)

1. Add a dedicated provider onboarding flow that guides users through provider selection, credential method, validation, and model readiness checks.
2. Introduce OpenAI OAuth sign-in path alongside existing API-key auth.
3. Add post-auth verification and user-facing status indicators (connected, needs action, failed with reason).
4. Include migration-safe handling so existing profiles/settings remain valid.

Trade-offs / risks (optional)

• OAuth introduces callback/session complexity and potential edge cases in remote/dev environments
• Additional onboarding UX must stay lightweight to avoid slowing experienced users
• Supporting both OAuth and API key paths increases testing matrix

Request checklist

• I've searched existing Issues and Discussions for duplicates
• This describes a specific problem with clear context and impact

[mojomast]

Issue #11676 Dev Plan

Issue: https://github.com/RooCodeInc/Roo-Code/issues/11676

Scope

• Primary scope: apps/cli onboarding and auth flow improvements to reduce setup friction.
• Key outcome: support OpenAI OAuth (openai-codex) in CLI without requiring manual API key entry.
• Compatibility: keep existing API-key provider flows (including openai-native) fully functional.

Approach

• Integrate OpenAI OAuth via the existing extension-managed openai-codex flow first.
• Reuse current extension OAuth logic (src/integrations/openai-codex/oauth.ts) instead of duplicating PKCE/callback/refresh behavior in CLI.

Acceptance Mapping (Issue -> Plan)

• Guided onboarding with clear defaults and feedback -> PR 2, PR 4, PR 6.
• OpenAI OAuth sign-in without manual key entry -> PR 1, PR 3, PR 4, PR 5.
• Existing API-key OpenAI flow continues to work -> PR 1, PR 2, test matrix.
• Actionable failure handling and clear auth state visibility -> PR 3, PR 5, PR 6.

---

PR 1: Provider Capability Plumbing

Goal: Teach CLI provider auth modes.

Files:

• apps/cli/src/types/types.ts
• apps/cli/src/lib/utils/provider.ts
• apps/cli/src/lib/utils/__tests__/provider.test.ts

Changes:

• Add openai-codex to supportedProviders.
• Add provider auth capability helpers.

Suggested signatures:

// apps/cli/src/lib/utils/provider.ts
export type ProviderAuthMode = "api-key" | "oauth" | "roo-token"

export function getProviderAuthMode(provider: SupportedProvider): ProviderAuthMode
export function providerRequiresApiKey(provider: SupportedProvider): boolean
export function providerSupportsOAuth(provider: SupportedProvider): boolean

Acceptance criteria:

• Unit tests verify:
  • openai-codex -> oauth
  • roo -> roo-token
  • existing providers -> api-key

---

PR 2: Run-Path Auth Branching

Goal: Remove forced API-key requirement for OAuth providers.

Files:

• apps/cli/src/commands/cli/run.ts
• apps/cli/src/commands/cli/__tests__/run.test.ts

Changes:

• Extract auth resolution from run() into focused helper(s).
• Branch auth behavior by provider capability.

Suggested signatures:

// apps/cli/src/commands/cli/run.ts
async function resolveProviderAuthentication(params: {
  provider: SupportedProvider
  flagApiKey?: string
  preloadedApiKey?: string
  rooToken: string | null
  settings: CliSettings
  host?: ExtensionHost
  interactive: boolean
}): Promise<{
  apiKey?: string
  rooUser?: User
  needsOAuthBootstrap?: boolean
}>

async function assertAuthReady(params: {
  provider: SupportedProvider
  auth: { apiKey?: string; needsOAuthBootstrap?: boolean }
  interactive: boolean
}): Promise<void>

Acceptance criteria:

• openai-codex no longer fails with “No API key provided”.
• Existing API-key provider behavior unchanged.

---

PR 3: Extension-Host OAuth Bridge (CLI Side)

Goal: Trigger openAiCodexSignIn from CLI and wait for auth state.

Files:

• apps/cli/src/agent/extension-host.ts
• apps/cli/src/agent/extension-client.ts
• apps/cli/src/agent/events.ts
• apps/cli/src/agent/__tests__/...

Changes:

• Add helper to request OpenAI OAuth sign-in and await completion.
• Expose provider auth state getter from extension state.

Suggested signatures:

// apps/cli/src/agent/extension-host.ts
public async ensureOpenAiCodexAuthenticated(options?: {
  timeoutMs?: number
}): Promise<{ success: true } | { success: false; reason: string }>

// apps/cli/src/agent/extension-client.ts
public getProviderAuthState(): {
  openAiCodexIsAuthenticated?: boolean
}

Behavior:

• If provider is openai-codex and not authenticated:
  • send { type: "openAiCodexSignIn" }
  • wait for openAiCodexIsAuthenticated === true
  • on timeout/failure, return actionable error

Acceptance criteria:

• Interactive mode can complete OAuth inside CLI flow.
• Timeout/port conflict/cancel errors are clear.

---

PR 4: Onboarding Integration

Goal: Add OpenAI OAuth path to TUI onboarding.

Files:

• apps/cli/src/ui/components/onboarding/OnboardingScreen.tsx
• apps/cli/src/lib/utils/onboarding.ts
• apps/cli/src/types/types.ts (if needed)

Changes:

• Add option like “Sign in with OpenAI (ChatGPT Plus/Pro)”.
• Return structured onboarding result for OAuth route.

Suggested signatures:

// apps/cli/src/types/types.ts
export type OnboardingAuthMethod = "roo-token" | "api-key" | "oauth"

export interface OnboardingResult {
  choice: OnboardingProviderChoice
  provider?: SupportedProvider
  authMethod?: OnboardingAuthMethod
  apiKey?: string
  token?: string
  skipped: boolean
}

Acceptance criteria:

• Users can complete onboarding without shell env vars for OpenAI Codex.
• Existing BYOK flow remains intact.

---

PR 5: Provider-Aware Auth Commands

Goal: Add explicit auth commands for OpenAI Codex.

Files:

• apps/cli/src/index.ts
• apps/cli/src/commands/auth/login.ts
• apps/cli/src/commands/auth/logout.ts
• apps/cli/src/commands/auth/status.ts

Changes:

• Add --provider to auth commands.
• Route by provider:
  • roo -> existing cloud login/logout/status
  • openai-codex -> extension-mediated sign-in/sign-out/status

Suggested signatures:

// apps/cli/src/commands/auth/login.ts
export async function login(options?: { provider?: SupportedProvider }): Promise<LoginResult>

// apps/cli/src/commands/auth/status.ts
export async function status(options?: { provider?: SupportedProvider }): Promise<void>

// apps/cli/src/commands/auth/logout.ts
export async function logout(options?: { provider?: SupportedProvider }): Promise<void>

Acceptance criteria:

• roo auth login --provider openai-codex works.
• roo auth status --provider openai-codex reports signed in/out.
• roo auth logout --provider openai-codex clears session.

---

PR 6: Non-Interactive Behavior + Docs

Goal: Predictable behavior in --print and updated docs.

Files:

• apps/cli/src/commands/cli/run.ts
• apps/cli/README.md

Changes:

• If OAuth-required provider is used in non-TTY mode without session, fail fast with guidance.
• Update docs for provider-specific auth modes and commands.

Suggested message:

• openai-codex requires interactive OAuth. Run in TTY or pre-auth with roo auth login --provider openai-codex.

Acceptance criteria:

• No hangs in non-interactive mode.
• README aligns with implementation.

---

Test Matrix

Run:

• pnpm --filter @roo-code/cli check-types
• pnpm --filter @roo-code/cli test

Cover:

• API-key provider via env var
• API-key provider via saved key
• Roo token provider
• OpenAI Codex interactive sign-in success
• OpenAI Codex sign-in timeout/failure
• OpenAI Codex non-interactive rejection path
• Auth status/logout for both roo and openai-codex

---

Execution Tracker

• PR 1 merged
• PR 2 merged
• PR 3 merged
• PR 4 merged
• PR 5 merged
• PR 6 merged
• End-to-end QA run on fresh CLI config directory
• Issue [ENHANCEMENT] Improve provider ingestion onboarding and add OpenAI OAuth #11676 updated with implementation summary and test evidence

[mojomast]

Implemented end-to-end on branch issue-11676-cli-onboarding-oauth following devplan.md (PR1 -> PR6), with backward compatibility preserved for existing API-key flows and Roo token auth.

Phase commits

• PR1 Provider capability plumbing: dcc3ea9e2
• PR2 Run-path auth branching: d94e66c4b
• PR3 Extension-host OAuth bridge: 64d37ffca
• PR4 Onboarding OAuth integration: 6e8d871f5
• PR5 Provider-aware auth commands: 06c1f91f1
• PR6 Non-interactive behavior + docs: e069890e5
• Follow-up fix (auth subcommand provider parsing): 137c0c21d

What was delivered

• Added provider auth capability model (api-key/oauth/roo-token) and openai-codex support.
• Refactored run-path auth resolution; openai-codex no longer blocked by API-key checks.
• Added CLI extension-host OAuth bridge (ensureOpenAiCodexAuthenticated) and provider auth state access.
• Added onboarding route: “Sign in with OpenAI (ChatGPT Plus/Pro)”, with structured auth method result.
• Added provider-aware auth commands:
  • roo auth login --provider openai-codex
  • roo auth status --provider openai-codex
  • roo auth logout --provider openai-codex
  • defaults without --provider remain Roo-compatible.
• Added non-interactive fail-fast for unauthenticated openai-codex with actionable guidance.
• Updated CLI README to match provider/auth behavior.

Test evidence

Repeated after each phase and at final state:

• pnpm --filter @roo-code/cli check-types ✅
• pnpm --filter @roo-code/cli test ✅

Final suite result:

• Test files: 32 passed | 1 skipped
• Tests: 495 passed | 1 skipped

Additional targeted validation:

• New unit coverage for onboarding result mapping (onboarding.test.ts) ✅
• New auth command routing tests (login/logout/status) ✅
• New run-path non-interactive OAuth fail-fast tests ✅

Fresh-config QA check:

• Ran auth status flows with temporary config dir (XDG_CONFIG_HOME=$(mktemp -d)) for:
  • auth status --provider roo (expected unauthenticated guidance)
  • auth status --provider openai-codex (expected provider-specific unauthenticated guidance)

[mojomast]

PR is now open: #11679

Follow-up from live validation:

• Added browser-launch support in CLI vscode shim (vscode.env.openExternal) instead of a no-op.
• Added manual fallback message with full OAuth URL when browser auto-open fails.

Commit: c04dc361f