move pi-mono into companion-cloud as apps/companion-os

- Copy all pi-mono source into apps/companion-os/
- Update Dockerfile to COPY pre-built binary instead of downloading from GitHub Releases
- Update deploy-staging.yml to build pi from source (bun compile) before Docker build
- Add apps/companion-os/** to path triggers
- No more cross-repo dispatch needed

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/ai/src/utils/event-stream.ts

@@ -0,0 +1,92 @@
+import type { AssistantMessage, AssistantMessageEvent } from "../types.js";
+
+// Generic event stream class for async iteration
+export class EventStream<T, R = T> implements AsyncIterable<T> {
+  private queue: T[] = [];
+  private waiting: ((value: IteratorResult<T>) => void)[] = [];
+  private done = false;
+  private finalResultPromise: Promise<R>;
+  private resolveFinalResult!: (result: R) => void;
+
+  constructor(
+    private isComplete: (event: T) => boolean,
+    private extractResult: (event: T) => R,
+  ) {
+    this.finalResultPromise = new Promise((resolve) => {
+      this.resolveFinalResult = resolve;
+    });
+  }
+
+  push(event: T): void {
+    if (this.done) return;
+
+    if (this.isComplete(event)) {
+      this.done = true;
+      this.resolveFinalResult(this.extractResult(event));
+    }
+
+    // Deliver to waiting consumer or queue it
+    const waiter = this.waiting.shift();
+    if (waiter) {
+      waiter({ value: event, done: false });
+    } else {
+      this.queue.push(event);
+    }
+  }
+
+  end(result?: R): void {
+    this.done = true;
+    if (result !== undefined) {
+      this.resolveFinalResult(result);
+    }
+    // Notify all waiting consumers that we're done
+    while (this.waiting.length > 0) {
+      const waiter = this.waiting.shift()!;
+      waiter({ value: undefined as any, done: true });
+    }
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    while (true) {
+      if (this.queue.length > 0) {
+        yield this.queue.shift()!;
+      } else if (this.done) {
+        return;
+      } else {
+        const result = await new Promise<IteratorResult<T>>((resolve) =>
+          this.waiting.push(resolve),
+        );
+        if (result.done) return;
+        yield result.value;
+      }
+    }
+  }
+
+  result(): Promise<R> {
+    return this.finalResultPromise;
+  }
+}
+
+export class AssistantMessageEventStream extends EventStream<
+  AssistantMessageEvent,
+  AssistantMessage
+> {
+  constructor() {
+    super(
+      (event) => event.type === "done" || event.type === "error",
+      (event) => {
+        if (event.type === "done") {
+          return event.message;
+        } else if (event.type === "error") {
+          return event.error;
+        }
+        throw new Error("Unexpected event type for final result");
+      },
+    );
+  }
+}
+
+/** Factory function for AssistantMessageEventStream (for use in extensions) */
+export function createAssistantMessageEventStream(): AssistantMessageEventStream {
+  return new AssistantMessageEventStream();
+}

packages/ai/src/utils/hash.ts

@@ -0,0 +1,17 @@
+/** Fast deterministic hash to shorten long strings */
+export function shortHash(str: string): string {
+  let h1 = 0xdeadbeef;
+  let h2 = 0x41c6ce57;
+  for (let i = 0; i < str.length; i++) {
+    const ch = str.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 =
+    Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^
+    Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 =
+    Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^
+    Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return (h2 >>> 0).toString(36) + (h1 >>> 0).toString(36);
+}

packages/ai/src/utils/json-parse.ts

@@ -0,0 +1,30 @@
+import { parse as partialParse } from "partial-json";
+
+/**
+ * Attempts to parse potentially incomplete JSON during streaming.
+ * Always returns a valid object, even if the JSON is incomplete.
+ *
+ * @param partialJson The partial JSON string from streaming
+ * @returns Parsed object or empty object if parsing fails
+ */
+export function parseStreamingJson<T = any>(
+  partialJson: string | undefined,
+): T {
+  if (!partialJson || partialJson.trim() === "") {
+    return {} as T;
+  }
+
+  // Try standard parsing first (fastest for complete JSON)
+  try {
+    return JSON.parse(partialJson) as T;
+  } catch {
+    // Try partial-json for incomplete JSON
+    try {
+      const result = partialParse(partialJson);
+      return (result ?? {}) as T;
+    } catch {
+      // If all parsing fails, return empty object
+      return {} as T;
+    }
+  }
+}

packages/ai/src/utils/oauth/anthropic.ts

@@ -0,0 +1,144 @@
+/**
+ * Anthropic OAuth flow (Claude Pro/Max)
+ */
+
+import { generatePKCE } from "./pkce.js";
+import type {
+  OAuthCredentials,
+  OAuthLoginCallbacks,
+  OAuthProviderInterface,
+} from "./types.js";
+
+const decode = (s: string) => atob(s);
+const CLIENT_ID = decode("OWQxYzI1MGEtZTYxYi00NGQ5LTg4ZWQtNTk0NGQxOTYyZjVl");
+const AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
+const TOKEN_URL = "https://console.anthropic.com/v1/oauth/token";
+const REDIRECT_URI = "https://console.anthropic.com/oauth/code/callback";
+const SCOPES = "org:create_api_key user:profile user:inference";
+
+/**
+ * Login with Anthropic OAuth (device code flow)
+ *
+ * @param onAuthUrl - Callback to handle the authorization URL (e.g., open browser)
+ * @param onPromptCode - Callback to prompt user for the authorization code
+ */
+export async function loginAnthropic(
+  onAuthUrl: (url: string) => void,
+  onPromptCode: () => Promise<string>,
+): Promise<OAuthCredentials> {
+  const { verifier, challenge } = await generatePKCE();
+
+  // Build authorization URL
+  const authParams = new URLSearchParams({
+    code: "true",
+    client_id: CLIENT_ID,
+    response_type: "code",
+    redirect_uri: REDIRECT_URI,
+    scope: SCOPES,
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    state: verifier,
+  });
+
+  const authUrl = `${AUTHORIZE_URL}?${authParams.toString()}`;
+
+  // Notify caller with URL to open
+  onAuthUrl(authUrl);
+
+  // Wait for user to paste authorization code (format: code#state)
+  const authCode = await onPromptCode();
+  const splits = authCode.split("#");
+  const code = splits[0];
+  const state = splits[1];
+
+  // Exchange code for tokens
+  const tokenResponse = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      grant_type: "authorization_code",
+      client_id: CLIENT_ID,
+      code: code,
+      state: state,
+      redirect_uri: REDIRECT_URI,
+      code_verifier: verifier,
+    }),
+  });
+
+  if (!tokenResponse.ok) {
+    const error = await tokenResponse.text();
+    throw new Error(`Token exchange failed: ${error}`);
+  }
+
+  const tokenData = (await tokenResponse.json()) as {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+  };
+
+  // Calculate expiry time (current time + expires_in seconds - 5 min buffer)
+  const expiresAt = Date.now() + tokenData.expires_in * 1000 - 5 * 60 * 1000;
+
+  // Save credentials
+  return {
+    refresh: tokenData.refresh_token,
+    access: tokenData.access_token,
+    expires: expiresAt,
+  };
+}
+
+/**
+ * Refresh Anthropic OAuth token
+ */
+export async function refreshAnthropicToken(
+  refreshToken: string,
+): Promise<OAuthCredentials> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      grant_type: "refresh_token",
+      client_id: CLIENT_ID,
+      refresh_token: refreshToken,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Anthropic token refresh failed: ${error}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+  };
+
+  return {
+    refresh: data.refresh_token,
+    access: data.access_token,
+    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
+  };
+}
+
+export const anthropicOAuthProvider: OAuthProviderInterface = {
+  id: "anthropic",
+  name: "Anthropic (Claude Pro/Max)",
+
+  async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+    return loginAnthropic(
+      (url) => callbacks.onAuth({ url }),
+      () => callbacks.onPrompt({ message: "Paste the authorization code:" }),
+    );
+  },
+
+  async refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+    return refreshAnthropicToken(credentials.refresh);
+  },
+
+  getApiKey(credentials: OAuthCredentials): string {
+    return credentials.access;
+  },
+};

packages/ai/src/utils/oauth/github-copilot.ts

@@ -0,0 +1,423 @@
+/**
+ * GitHub Copilot OAuth flow
+ */
+
+import { getModels } from "../../models.js";
+import type { Api, Model } from "../../types.js";
+import type {
+  OAuthCredentials,
+  OAuthLoginCallbacks,
+  OAuthProviderInterface,
+} from "./types.js";
+
+type CopilotCredentials = OAuthCredentials & {
+  enterpriseUrl?: string;
+};
+
+const decode = (s: string) => atob(s);
+const CLIENT_ID = decode("SXYxLmI1MDdhMDhjODdlY2ZlOTg=");
+
+const COPILOT_HEADERS = {
+  "User-Agent": "GitHubCopilotChat/0.35.0",
+  "Editor-Version": "vscode/1.107.0",
+  "Editor-Plugin-Version": "copilot-chat/0.35.0",
+  "Copilot-Integration-Id": "vscode-chat",
+} as const;
+
+type DeviceCodeResponse = {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  interval: number;
+  expires_in: number;
+};
+
+type DeviceTokenSuccessResponse = {
+  access_token: string;
+  token_type?: string;
+  scope?: string;
+};
+
+type DeviceTokenErrorResponse = {
+  error: string;
+  error_description?: string;
+  interval?: number;
+};
+
+export function normalizeDomain(input: string): string | null {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+  try {
+    const url = trimmed.includes("://")
+      ? new URL(trimmed)
+      : new URL(`https://${trimmed}`);
+    return url.hostname;
+  } catch {
+    return null;
+  }
+}
+
+function getUrls(domain: string): {
+  deviceCodeUrl: string;
+  accessTokenUrl: string;
+  copilotTokenUrl: string;
+} {
+  return {
+    deviceCodeUrl: `https://${domain}/login/device/code`,
+    accessTokenUrl: `https://${domain}/login/oauth/access_token`,
+    copilotTokenUrl: `https://api.${domain}/copilot_internal/v2/token`,
+  };
+}
+
+/**
+ * Parse the proxy-ep from a Copilot token and convert to API base URL.
+ * Token format: tid=...;exp=...;proxy-ep=proxy.individual.githubcopilot.com;...
+ * Returns API URL like https://api.individual.githubcopilot.com
+ */
+function getBaseUrlFromToken(token: string): string | null {
+  const match = token.match(/proxy-ep=([^;]+)/);
+  if (!match) return null;
+  const proxyHost = match[1];
+  // Convert proxy.xxx to api.xxx
+  const apiHost = proxyHost.replace(/^proxy\./, "api.");
+  return `https://${apiHost}`;
+}
+
+export function getGitHubCopilotBaseUrl(
+  token?: string,
+  enterpriseDomain?: string,
+): string {
+  // If we have a token, extract the base URL from proxy-ep
+  if (token) {
+    const urlFromToken = getBaseUrlFromToken(token);
+    if (urlFromToken) return urlFromToken;
+  }
+  // Fallback for enterprise or if token parsing fails
+  if (enterpriseDomain) return `https://copilot-api.${enterpriseDomain}`;
+  return "https://api.individual.githubcopilot.com";
+}
+
+async function fetchJson(url: string, init: RequestInit): Promise<unknown> {
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`${response.status} ${response.statusText}: ${text}`);
+  }
+  return response.json();
+}
+
+async function startDeviceFlow(domain: string): Promise<DeviceCodeResponse> {
+  const urls = getUrls(domain);
+  const data = await fetchJson(urls.deviceCodeUrl, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "User-Agent": "GitHubCopilotChat/0.35.0",
+    },
+    body: JSON.stringify({
+      client_id: CLIENT_ID,
+      scope: "read:user",
+    }),
+  });
+
+  if (!data || typeof data !== "object") {
+    throw new Error("Invalid device code response");
+  }
+
+  const deviceCode = (data as Record<string, unknown>).device_code;
+  const userCode = (data as Record<string, unknown>).user_code;
+  const verificationUri = (data as Record<string, unknown>).verification_uri;
+  const interval = (data as Record<string, unknown>).interval;
+  const expiresIn = (data as Record<string, unknown>).expires_in;
+
+  if (
+    typeof deviceCode !== "string" ||
+    typeof userCode !== "string" ||
+    typeof verificationUri !== "string" ||
+    typeof interval !== "number" ||
+    typeof expiresIn !== "number"
+  ) {
+    throw new Error("Invalid device code response fields");
+  }
+
+  return {
+    device_code: deviceCode,
+    user_code: userCode,
+    verification_uri: verificationUri,
+    interval,
+    expires_in: expiresIn,
+  };
+}
+
+/**
+ * Sleep that can be interrupted by an AbortSignal
+ */
+function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Login cancelled"));
+      return;
+    }
+
+    const timeout = setTimeout(resolve, ms);
+
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timeout);
+        reject(new Error("Login cancelled"));
+      },
+      { once: true },
+    );
+  });
+}
+
+async function pollForGitHubAccessToken(
+  domain: string,
+  deviceCode: string,
+  intervalSeconds: number,
+  expiresIn: number,
+  signal?: AbortSignal,
+) {
+  const urls = getUrls(domain);
+  const deadline = Date.now() + expiresIn * 1000;
+  let intervalMs = Math.max(1000, Math.floor(intervalSeconds * 1000));
+
+  while (Date.now() < deadline) {
+    if (signal?.aborted) {
+      throw new Error("Login cancelled");
+    }
+
+    const raw = await fetchJson(urls.accessTokenUrl, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": "GitHubCopilotChat/0.35.0",
+      },
+      body: JSON.stringify({
+        client_id: CLIENT_ID,
+        device_code: deviceCode,
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+      }),
+    });
+
+    if (
+      raw &&
+      typeof raw === "object" &&
+      typeof (raw as DeviceTokenSuccessResponse).access_token === "string"
+    ) {
+      return (raw as DeviceTokenSuccessResponse).access_token;
+    }
+
+    if (
+      raw &&
+      typeof raw === "object" &&
+      typeof (raw as DeviceTokenErrorResponse).error === "string"
+    ) {
+      const err = (raw as DeviceTokenErrorResponse).error;
+      if (err === "authorization_pending") {
+        await abortableSleep(intervalMs, signal);
+        continue;
+      }
+
+      if (err === "slow_down") {
+        intervalMs += 5000;
+        await abortableSleep(intervalMs, signal);
+        continue;
+      }
+
+      throw new Error(`Device flow failed: ${err}`);
+    }
+
+    await abortableSleep(intervalMs, signal);
+  }
+
+  throw new Error("Device flow timed out");
+}
+
+/**
+ * Refresh GitHub Copilot token
+ */
+export async function refreshGitHubCopilotToken(
+  refreshToken: string,
+  enterpriseDomain?: string,
+): Promise<OAuthCredentials> {
+  const domain = enterpriseDomain || "github.com";
+  const urls = getUrls(domain);
+
+  const raw = await fetchJson(urls.copilotTokenUrl, {
+    headers: {
+      Accept: "application/json",
+      Authorization: `Bearer ${refreshToken}`,
+      ...COPILOT_HEADERS,
+    },
+  });
+
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Invalid Copilot token response");
+  }
+
+  const token = (raw as Record<string, unknown>).token;
+  const expiresAt = (raw as Record<string, unknown>).expires_at;
+
+  if (typeof token !== "string" || typeof expiresAt !== "number") {
+    throw new Error("Invalid Copilot token response fields");
+  }
+
+  return {
+    refresh: refreshToken,
+    access: token,
+    expires: expiresAt * 1000 - 5 * 60 * 1000,
+    enterpriseUrl: enterpriseDomain,
+  };
+}
+
+/**
+ * Enable a model for the user's GitHub Copilot account.
+ * This is required for some models (like Claude, Grok) before they can be used.
+ */
+async function enableGitHubCopilotModel(
+  token: string,
+  modelId: string,
+  enterpriseDomain?: string,
+): Promise<boolean> {
+  const baseUrl = getGitHubCopilotBaseUrl(token, enterpriseDomain);
+  const url = `${baseUrl}/models/${modelId}/policy`;
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${token}`,
+        ...COPILOT_HEADERS,
+        "openai-intent": "chat-policy",
+        "x-interaction-type": "chat-policy",
+      },
+      body: JSON.stringify({ state: "enabled" }),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Enable all known GitHub Copilot models that may require policy acceptance.
+ * Called after successful login to ensure all models are available.
+ */
+async function enableAllGitHubCopilotModels(
+  token: string,
+  enterpriseDomain?: string,
+  onProgress?: (model: string, success: boolean) => void,
+): Promise<void> {
+  const models = getModels("github-copilot");
+  await Promise.all(
+    models.map(async (model) => {
+      const success = await enableGitHubCopilotModel(
+        token,
+        model.id,
+        enterpriseDomain,
+      );
+      onProgress?.(model.id, success);
+    }),
+  );
+}
+
+/**
+ * Login with GitHub Copilot OAuth (device code flow)
+ *
+ * @param options.onAuth - Callback with URL and optional instructions (user code)
+ * @param options.onPrompt - Callback to prompt user for input
+ * @param options.onProgress - Optional progress callback
+ * @param options.signal - Optional AbortSignal for cancellation
+ */
+export async function loginGitHubCopilot(options: {
+  onAuth: (url: string, instructions?: string) => void;
+  onPrompt: (prompt: {
+    message: string;
+    placeholder?: string;
+    allowEmpty?: boolean;
+  }) => Promise<string>;
+  onProgress?: (message: string) => void;
+  signal?: AbortSignal;
+}): Promise<OAuthCredentials> {
+  const input = await options.onPrompt({
+    message: "GitHub Enterprise URL/domain (blank for github.com)",
+    placeholder: "company.ghe.com",
+    allowEmpty: true,
+  });
+
+  if (options.signal?.aborted) {
+    throw new Error("Login cancelled");
+  }
+
+  const trimmed = input.trim();
+  const enterpriseDomain = normalizeDomain(input);
+  if (trimmed && !enterpriseDomain) {
+    throw new Error("Invalid GitHub Enterprise URL/domain");
+  }
+  const domain = enterpriseDomain || "github.com";
+
+  const device = await startDeviceFlow(domain);
+  options.onAuth(device.verification_uri, `Enter code: ${device.user_code}`);
+
+  const githubAccessToken = await pollForGitHubAccessToken(
+    domain,
+    device.device_code,
+    device.interval,
+    device.expires_in,
+    options.signal,
+  );
+  const credentials = await refreshGitHubCopilotToken(
+    githubAccessToken,
+    enterpriseDomain ?? undefined,
+  );
+
+  // Enable all models after successful login
+  options.onProgress?.("Enabling models...");
+  await enableAllGitHubCopilotModels(
+    credentials.access,
+    enterpriseDomain ?? undefined,
+  );
+  return credentials;
+}
+
+export const githubCopilotOAuthProvider: OAuthProviderInterface = {
+  id: "github-copilot",
+  name: "GitHub Copilot",
+
+  async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+    return loginGitHubCopilot({
+      onAuth: (url, instructions) => callbacks.onAuth({ url, instructions }),
+      onPrompt: callbacks.onPrompt,
+      onProgress: callbacks.onProgress,
+      signal: callbacks.signal,
+    });
+  },
+
+  async refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+    const creds = credentials as CopilotCredentials;
+    return refreshGitHubCopilotToken(creds.refresh, creds.enterpriseUrl);
+  },
+
+  getApiKey(credentials: OAuthCredentials): string {
+    return credentials.access;
+  },
+
+  modifyModels(
+    models: Model<Api>[],
+    credentials: OAuthCredentials,
+  ): Model<Api>[] {
+    const creds = credentials as CopilotCredentials;
+    const domain = creds.enterpriseUrl
+      ? (normalizeDomain(creds.enterpriseUrl) ?? undefined)
+      : undefined;
+    const baseUrl = getGitHubCopilotBaseUrl(creds.access, domain);
+    return models.map((m) =>
+      m.provider === "github-copilot" ? { ...m, baseUrl } : m,
+    );
+  },
+};

packages/ai/src/utils/oauth/google-antigravity.ts

@@ -0,0 +1,492 @@
+/**
+ * Antigravity OAuth flow (Gemini 3, Claude, GPT-OSS via Google Cloud)
+ * Uses different OAuth credentials than google-gemini-cli for access to additional models.
+ *
+ * NOTE: This module uses Node.js http.createServer for the OAuth callback.
+ * It is only intended for CLI use, not browser environments.
+ */
+
+import type { Server } from "node:http";
+import { generatePKCE } from "./pkce.js";
+import type {
+  OAuthCredentials,
+  OAuthLoginCallbacks,
+  OAuthProviderInterface,
+} from "./types.js";
+
+type AntigravityCredentials = OAuthCredentials & {
+  projectId: string;
+};
+
+let _createServer: typeof import("node:http").createServer | null = null;
+let _httpImportPromise: Promise<void> | null = null;
+if (
+  typeof process !== "undefined" &&
+  (process.versions?.node || process.versions?.bun)
+) {
+  _httpImportPromise = import("node:http").then((m) => {
+    _createServer = m.createServer;
+  });
+}
+
+// Antigravity OAuth credentials (different from Gemini CLI)
+const decode = (s: string) => atob(s);
+const CLIENT_ID = decode(
+  "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ==",
+);
+const CLIENT_SECRET = decode(
+  "R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=",
+);
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+// Antigravity requires additional scopes
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+  "https://www.googleapis.com/auth/cclog",
+  "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+// Fallback project ID when discovery fails
+const DEFAULT_PROJECT_ID = "rising-fact-p41fc";
+
+type CallbackServerInfo = {
+  server: Server;
+  cancelWait: () => void;
+  waitForCode: () => Promise<{ code: string; state: string } | null>;
+};
+
+/**
+ * Start a local HTTP server to receive the OAuth callback
+ */
+async function getNodeCreateServer(): Promise<
+  typeof import("node:http").createServer
+> {
+  if (_createServer) return _createServer;
+  if (_httpImportPromise) {
+    await _httpImportPromise;
+  }
+  if (_createServer) return _createServer;
+  throw new Error(
+    "Antigravity OAuth is only available in Node.js environments",
+  );
+}
+
+async function startCallbackServer(): Promise<CallbackServerInfo> {
+  const createServer = await getNodeCreateServer();
+
+  return new Promise((resolve, reject) => {
+    let result: { code: string; state: string } | null = null;
+    let cancelled = false;
+
+    const server = createServer((req, res) => {
+      const url = new URL(req.url || "", `http://localhost:51121`);
+
+      if (url.pathname === "/oauth-callback") {
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        const error = url.searchParams.get("error");
+
+        if (error) {
+          res.writeHead(400, { "Content-Type": "text/html" });
+          res.end(
+            `<html><body><h1>Authentication Failed</h1><p>Error: ${error}</p><p>You can close this window.</p></body></html>`,
+          );
+          return;
+        }
+
+        if (code && state) {
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end(
+            `<html><body><h1>Authentication Successful</h1><p>You can close this window and return to the terminal.</p></body></html>`,
+          );
+          result = { code, state };
+        } else {
+          res.writeHead(400, { "Content-Type": "text/html" });
+          res.end(
+            `<html><body><h1>Authentication Failed</h1><p>Missing code or state parameter.</p></body></html>`,
+          );
+        }
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+
+    server.on("error", (err) => {
+      reject(err);
+    });
+
+    server.listen(51121, "127.0.0.1", () => {
+      resolve({
+        server,
+        cancelWait: () => {
+          cancelled = true;
+        },
+        waitForCode: async () => {
+          const sleep = () => new Promise((r) => setTimeout(r, 100));
+          while (!result && !cancelled) {
+            await sleep();
+          }
+          return result;
+        },
+      });
+    });
+  });
+}
+
+/**
+ * Parse redirect URL to extract code and state
+ */
+function parseRedirectUrl(input: string): { code?: string; state?: string } {
+  const value = input.trim();
+  if (!value) return {};
+
+  try {
+    const url = new URL(value);
+    return {
+      code: url.searchParams.get("code") ?? undefined,
+      state: url.searchParams.get("state") ?? undefined,
+    };
+  } catch {
+    // Not a URL, return empty
+    return {};
+  }
+}
+
+interface LoadCodeAssistPayload {
+  cloudaicompanionProject?: string | { id?: string };
+  currentTier?: { id?: string };
+  allowedTiers?: Array<{ id?: string; isDefault?: boolean }>;
+}
+
+/**
+ * Discover or provision a project for the user
+ */
+async function discoverProject(
+  accessToken: string,
+  onProgress?: (message: string) => void,
+): Promise<string> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "google-api-nodejs-client/9.15.1",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    "Client-Metadata": JSON.stringify({
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+    }),
+  };
+
+  // Try endpoints in order: prod first, then sandbox
+  const endpoints = [
+    "https://cloudcode-pa.googleapis.com",
+    "https://daily-cloudcode-pa.sandbox.googleapis.com",
+  ];
+
+  onProgress?.("Checking for existing project...");
+
+  for (const endpoint of endpoints) {
+    try {
+      const loadResponse = await fetch(
+        `${endpoint}/v1internal:loadCodeAssist`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            metadata: {
+              ideType: "IDE_UNSPECIFIED",
+              platform: "PLATFORM_UNSPECIFIED",
+              pluginType: "GEMINI",
+            },
+          }),
+        },
+      );
+
+      if (loadResponse.ok) {
+        const data = (await loadResponse.json()) as LoadCodeAssistPayload;
+
+        // Handle both string and object formats
+        if (
+          typeof data.cloudaicompanionProject === "string" &&
+          data.cloudaicompanionProject
+        ) {
+          return data.cloudaicompanionProject;
+        }
+        if (
+          data.cloudaicompanionProject &&
+          typeof data.cloudaicompanionProject === "object" &&
+          data.cloudaicompanionProject.id
+        ) {
+          return data.cloudaicompanionProject.id;
+        }
+      }
+    } catch {
+      // Try next endpoint
+    }
+  }
+
+  // Use fallback project ID
+  onProgress?.("Using default project...");
+  return DEFAULT_PROJECT_ID;
+}
+
+/**
+ * Get user email from the access token
+ */
+async function getUserEmail(accessToken: string): Promise<string | undefined> {
+  try {
+    const response = await fetch(
+      "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+      {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+        },
+      },
+    );
+
+    if (response.ok) {
+      const data = (await response.json()) as { email?: string };
+      return data.email;
+    }
+  } catch {
+    // Ignore errors, email is optional
+  }
+  return undefined;
+}
+
+/**
+ * Refresh Antigravity token
+ */
+export async function refreshAntigravityToken(
+  refreshToken: string,
+  projectId: string,
+): Promise<OAuthCredentials> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      refresh_token: refreshToken,
+      grant_type: "refresh_token",
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Antigravity token refresh failed: ${error}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token: string;
+    expires_in: number;
+    refresh_token?: string;
+  };
+
+  return {
+    refresh: data.refresh_token || refreshToken,
+    access: data.access_token,
+    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
+    projectId,
+  };
+}
+
+/**
+ * Login with Antigravity OAuth
+ *
+ * @param onAuth - Callback with URL and optional instructions
+ * @param onProgress - Optional progress callback
+ * @param onManualCodeInput - Optional promise that resolves with user-pasted redirect URL.
+ *                            Races with browser callback - whichever completes first wins.
+ */
+export async function loginAntigravity(
+  onAuth: (info: { url: string; instructions?: string }) => void,
+  onProgress?: (message: string) => void,
+  onManualCodeInput?: () => Promise<string>,
+): Promise<OAuthCredentials> {
+  const { verifier, challenge } = await generatePKCE();
+
+  // Start local server for callback
+  onProgress?.("Starting local server for OAuth callback...");
+  const server = await startCallbackServer();
+
+  let code: string | undefined;
+
+  try {
+    // Build authorization URL
+    const authParams = new URLSearchParams({
+      client_id: CLIENT_ID,
+      response_type: "code",
+      redirect_uri: REDIRECT_URI,
+      scope: SCOPES.join(" "),
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      state: verifier,
+      access_type: "offline",
+      prompt: "consent",
+    });
+
+    const authUrl = `${AUTH_URL}?${authParams.toString()}`;
+
+    // Notify caller with URL to open
+    onAuth({
+      url: authUrl,
+      instructions: "Complete the sign-in in your browser.",
+    });
+
+    // Wait for the callback, racing with manual input if provided
+    onProgress?.("Waiting for OAuth callback...");
+
+    if (onManualCodeInput) {
+      // Race between browser callback and manual input
+      let manualInput: string | undefined;
+      let manualError: Error | undefined;
+      const manualPromise = onManualCodeInput()
+        .then((input) => {
+          manualInput = input;
+          server.cancelWait();
+        })
+        .catch((err) => {
+          manualError = err instanceof Error ? err : new Error(String(err));
+          server.cancelWait();
+        });
+
+      const result = await server.waitForCode();
+
+      // If manual input was cancelled, throw that error
+      if (manualError) {
+        throw manualError;
+      }
+
+      if (result?.code) {
+        // Browser callback won - verify state
+        if (result.state !== verifier) {
+          throw new Error("OAuth state mismatch - possible CSRF attack");
+        }
+        code = result.code;
+      } else if (manualInput) {
+        // Manual input won
+        const parsed = parseRedirectUrl(manualInput);
+        if (parsed.state && parsed.state !== verifier) {
+          throw new Error("OAuth state mismatch - possible CSRF attack");
+        }
+        code = parsed.code;
+      }
+
+      // If still no code, wait for manual promise and try that
+      if (!code) {
+        await manualPromise;
+        if (manualError) {
+          throw manualError;
+        }
+        if (manualInput) {
+          const parsed = parseRedirectUrl(manualInput);
+          if (parsed.state && parsed.state !== verifier) {
+            throw new Error("OAuth state mismatch - possible CSRF attack");
+          }
+          code = parsed.code;
+        }
+      }
+    } else {
+      // Original flow: just wait for callback
+      const result = await server.waitForCode();
+      if (result?.code) {
+        if (result.state !== verifier) {
+          throw new Error("OAuth state mismatch - possible CSRF attack");
+        }
+        code = result.code;
+      }
+    }
+
+    if (!code) {
+      throw new Error("No authorization code received");
+    }
+
+    // Exchange code for tokens
+    onProgress?.("Exchanging authorization code for tokens...");
+    const tokenResponse = await fetch(TOKEN_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        client_id: CLIENT_ID,
+        client_secret: CLIENT_SECRET,
+        code,
+        grant_type: "authorization_code",
+        redirect_uri: REDIRECT_URI,
+        code_verifier: verifier,
+      }),
+    });
+
+    if (!tokenResponse.ok) {
+      const error = await tokenResponse.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    const tokenData = (await tokenResponse.json()) as {
+      access_token: string;
+      refresh_token: string;
+      expires_in: number;
+    };
+
+    if (!tokenData.refresh_token) {
+      throw new Error("No refresh token received. Please try again.");
+    }
+
+    // Get user email
+    onProgress?.("Getting user info...");
+    const email = await getUserEmail(tokenData.access_token);
+
+    // Discover project
+    const projectId = await discoverProject(tokenData.access_token, onProgress);
+
+    // Calculate expiry time (current time + expires_in seconds - 5 min buffer)
+    const expiresAt = Date.now() + tokenData.expires_in * 1000 - 5 * 60 * 1000;
+
+    const credentials: OAuthCredentials = {
+      refresh: tokenData.refresh_token,
+      access: tokenData.access_token,
+      expires: expiresAt,
+      projectId,
+      email,
+    };
+
+    return credentials;
+  } finally {
+    server.server.close();
+  }
+}
+
+export const antigravityOAuthProvider: OAuthProviderInterface = {
+  id: "google-antigravity",
+  name: "Antigravity (Gemini 3, Claude, GPT-OSS)",
+  usesCallbackServer: true,
+
+  async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+    return loginAntigravity(
+      callbacks.onAuth,
+      callbacks.onProgress,
+      callbacks.onManualCodeInput,
+    );
+  },
+
+  async refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+    const creds = credentials as AntigravityCredentials;
+    if (!creds.projectId) {
+      throw new Error("Antigravity credentials missing projectId");
+    }
+    return refreshAntigravityToken(creds.refresh, creds.projectId);
+  },
+
+  getApiKey(credentials: OAuthCredentials): string {
+    const creds = credentials as AntigravityCredentials;
+    return JSON.stringify({ token: creds.access, projectId: creds.projectId });
+  },
+};

packages/ai/src/utils/oauth/google-gemini-cli.ts

@@ -0,0 +1,648 @@
+/**
+ * Gemini CLI OAuth flow (Google Cloud Code Assist)
+ * Standard Gemini models only (gemini-2.0-flash, gemini-2.5-*)
+ *
+ * NOTE: This module uses Node.js http.createServer for the OAuth callback.
+ * It is only intended for CLI use, not browser environments.
+ */
+
+import type { Server } from "node:http";
+import { generatePKCE } from "./pkce.js";
+import type {
+  OAuthCredentials,
+  OAuthLoginCallbacks,
+  OAuthProviderInterface,
+} from "./types.js";
+
+type GeminiCredentials = OAuthCredentials & {
+  projectId: string;
+};
+
+let _createServer: typeof import("node:http").createServer | null = null;
+let _httpImportPromise: Promise<void> | null = null;
+if (
+  typeof process !== "undefined" &&
+  (process.versions?.node || process.versions?.bun)
+) {
+  _httpImportPromise = import("node:http").then((m) => {
+    _createServer = m.createServer;
+  });
+}
+
+const decode = (s: string) => atob(s);
+const CLIENT_ID = decode(
+  "NjgxMjU1ODA5Mzk1LW9vOGZ0Mm9wcmRybnA5ZTNhcWY2YXYzaG1kaWIxMzVqLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29t",
+);
+const CLIENT_SECRET = decode(
+  "R09DU1BYLTR1SGdNUG0tMW83U2stZ2VWNkN1NWNsWEZzeGw=",
+);
+const REDIRECT_URI = "http://localhost:8085/oauth2callback";
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+];
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+const CODE_ASSIST_ENDPOINT = "https://cloudcode-pa.googleapis.com";
+
+type CallbackServerInfo = {
+  server: Server;
+  cancelWait: () => void;
+  waitForCode: () => Promise<{ code: string; state: string } | null>;
+};
+
+/**
+ * Start a local HTTP server to receive the OAuth callback
+ */
+async function getNodeCreateServer(): Promise<
+  typeof import("node:http").createServer
+> {
+  if (_createServer) return _createServer;
+  if (_httpImportPromise) {
+    await _httpImportPromise;
+  }
+  if (_createServer) return _createServer;
+  throw new Error("Gemini CLI OAuth is only available in Node.js environments");
+}
+
+async function startCallbackServer(): Promise<CallbackServerInfo> {
+  const createServer = await getNodeCreateServer();
+
+  return new Promise((resolve, reject) => {
+    let result: { code: string; state: string } | null = null;
+    let cancelled = false;
+
+    const server = createServer((req, res) => {
+      const url = new URL(req.url || "", `http://localhost:8085`);
+
+      if (url.pathname === "/oauth2callback") {
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        const error = url.searchParams.get("error");
+
+        if (error) {
+          res.writeHead(400, { "Content-Type": "text/html" });
+          res.end(
+            `<html><body><h1>Authentication Failed</h1><p>Error: ${error}</p><p>You can close this window.</p></body></html>`,
+          );
+          return;
+        }
+
+        if (code && state) {
+          res.writeHead(200, { "Content-Type": "text/html" });
+          res.end(
+            `<html><body><h1>Authentication Successful</h1><p>You can close this window and return to the terminal.</p></body></html>`,
+          );
+          result = { code, state };
+        } else {
+          res.writeHead(400, { "Content-Type": "text/html" });
+          res.end(
+            `<html><body><h1>Authentication Failed</h1><p>Missing code or state parameter.</p></body></html>`,
+          );
+        }
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+
+    server.on("error", (err) => {
+      reject(err);
+    });
+
+    server.listen(8085, "127.0.0.1", () => {
+      resolve({
+        server,
+        cancelWait: () => {
+          cancelled = true;
+        },
+        waitForCode: async () => {
+          const sleep = () => new Promise((r) => setTimeout(r, 100));
+          while (!result && !cancelled) {
+            await sleep();
+          }
+          return result;
+        },
+      });
+    });
+  });
+}
+
+/**
+ * Parse redirect URL to extract code and state
+ */
+function parseRedirectUrl(input: string): { code?: string; state?: string } {
+  const value = input.trim();
+  if (!value) return {};
+
+  try {
+    const url = new URL(value);
+    return {
+      code: url.searchParams.get("code") ?? undefined,
+      state: url.searchParams.get("state") ?? undefined,
+    };
+  } catch {
+    // Not a URL, return empty
+    return {};
+  }
+}
+
+interface LoadCodeAssistPayload {
+  cloudaicompanionProject?: string;
+  currentTier?: { id?: string };
+  allowedTiers?: Array<{ id?: string; isDefault?: boolean }>;
+}
+
+/**
+ * Long-running operation response from onboardUser
+ */
+interface LongRunningOperationResponse {
+  name?: string;
+  done?: boolean;
+  response?: {
+    cloudaicompanionProject?: { id?: string };
+  };
+}
+
+// Tier IDs as used by the Cloud Code API
+const TIER_FREE = "free-tier";
+const TIER_LEGACY = "legacy-tier";
+const TIER_STANDARD = "standard-tier";
+
+interface GoogleRpcErrorResponse {
+  error?: {
+    details?: Array<{ reason?: string }>;
+  };
+}
+
+/**
+ * Wait helper for onboarding retries
+ */
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Get default tier from allowed tiers
+ */
+function getDefaultTier(
+  allowedTiers?: Array<{ id?: string; isDefault?: boolean }>,
+): { id?: string } {
+  if (!allowedTiers || allowedTiers.length === 0) return { id: TIER_LEGACY };
+  const defaultTier = allowedTiers.find((t) => t.isDefault);
+  return defaultTier ?? { id: TIER_LEGACY };
+}
+
+function isVpcScAffectedUser(payload: unknown): boolean {
+  if (!payload || typeof payload !== "object") return false;
+  if (!("error" in payload)) return false;
+  const error = (payload as GoogleRpcErrorResponse).error;
+  if (!error?.details || !Array.isArray(error.details)) return false;
+  return error.details.some(
+    (detail) => detail.reason === "SECURITY_POLICY_VIOLATED",
+  );
+}
+
+/**
+ * Poll a long-running operation until completion
+ */
+async function pollOperation(
+  operationName: string,
+  headers: Record<string, string>,
+  onProgress?: (message: string) => void,
+): Promise<LongRunningOperationResponse> {
+  let attempt = 0;
+  while (true) {
+    if (attempt > 0) {
+      onProgress?.(
+        `Waiting for project provisioning (attempt ${attempt + 1})...`,
+      );
+      await wait(5000);
+    }
+
+    const response = await fetch(
+      `${CODE_ASSIST_ENDPOINT}/v1internal/${operationName}`,
+      {
+        method: "GET",
+        headers,
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to poll operation: ${response.status} ${response.statusText}`,
+      );
+    }
+
+    const data = (await response.json()) as LongRunningOperationResponse;
+    if (data.done) {
+      return data;
+    }
+
+    attempt += 1;
+  }
+}
+
+/**
+ * Discover or provision a Google Cloud project for the user
+ */
+async function discoverProject(
+  accessToken: string,
+  onProgress?: (message: string) => void,
+): Promise<string> {
+  // Check for user-provided project ID via environment variable
+  const envProjectId =
+    process.env.GOOGLE_CLOUD_PROJECT || process.env.GOOGLE_CLOUD_PROJECT_ID;
+
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "google-api-nodejs-client/9.15.1",
+    "X-Goog-Api-Client": "gl-node/22.17.0",
+  };
+
+  // Try to load existing project via loadCodeAssist
+  onProgress?.("Checking for existing Cloud Code Assist project...");
+  const loadResponse = await fetch(
+    `${CODE_ASSIST_ENDPOINT}/v1internal:loadCodeAssist`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        cloudaicompanionProject: envProjectId,
+        metadata: {
+          ideType: "IDE_UNSPECIFIED",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+          duetProject: envProjectId,
+        },
+      }),
+    },
+  );
+
+  let data: LoadCodeAssistPayload;
+
+  if (!loadResponse.ok) {
+    let errorPayload: unknown;
+    try {
+      errorPayload = await loadResponse.clone().json();
+    } catch {
+      errorPayload = undefined;
+    }
+
+    if (isVpcScAffectedUser(errorPayload)) {
+      data = { currentTier: { id: TIER_STANDARD } };
+    } else {
+      const errorText = await loadResponse.text();
+      throw new Error(
+        `loadCodeAssist failed: ${loadResponse.status} ${loadResponse.statusText}: ${errorText}`,
+      );
+    }
+  } else {
+    data = (await loadResponse.json()) as LoadCodeAssistPayload;
+  }
+
+  // If user already has a current tier and project, use it
+  if (data.currentTier) {
+    if (data.cloudaicompanionProject) {
+      return data.cloudaicompanionProject;
+    }
+    // User has a tier but no managed project - they need to provide one via env var
+    if (envProjectId) {
+      return envProjectId;
+    }
+    throw new Error(
+      "This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID environment variable. " +
+        "See https://goo.gle/gemini-cli-auth-docs#workspace-gca",
+    );
+  }
+
+  // User needs to be onboarded - get the default tier
+  const tier = getDefaultTier(data.allowedTiers);
+  const tierId = tier?.id ?? TIER_FREE;
+
+  if (tierId !== TIER_FREE && !envProjectId) {
+    throw new Error(
+      "This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID environment variable. " +
+        "See https://goo.gle/gemini-cli-auth-docs#workspace-gca",
+    );
+  }
+
+  onProgress?.(
+    "Provisioning Cloud Code Assist project (this may take a moment)...",
+  );
+
+  // Build onboard request - for free tier, don't include project ID (Google provisions one)
+  // For other tiers, include the user's project ID if available
+  const onboardBody: Record<string, unknown> = {
+    tierId,
+    metadata: {
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+    },
+  };
+
+  if (tierId !== TIER_FREE && envProjectId) {
+    onboardBody.cloudaicompanionProject = envProjectId;
+    (onboardBody.metadata as Record<string, unknown>).duetProject =
+      envProjectId;
+  }
+
+  // Start onboarding - this returns a long-running operation
+  const onboardResponse = await fetch(
+    `${CODE_ASSIST_ENDPOINT}/v1internal:onboardUser`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify(onboardBody),
+    },
+  );
+
+  if (!onboardResponse.ok) {
+    const errorText = await onboardResponse.text();
+    throw new Error(
+      `onboardUser failed: ${onboardResponse.status} ${onboardResponse.statusText}: ${errorText}`,
+    );
+  }
+
+  let lroData = (await onboardResponse.json()) as LongRunningOperationResponse;
+
+  // If the operation isn't done yet, poll until completion
+  if (!lroData.done && lroData.name) {
+    lroData = await pollOperation(lroData.name, headers, onProgress);
+  }
+
+  // Try to get project ID from the response
+  const projectId = lroData.response?.cloudaicompanionProject?.id;
+  if (projectId) {
+    return projectId;
+  }
+
+  // If no project ID from onboarding, fall back to env var
+  if (envProjectId) {
+    return envProjectId;
+  }
+
+  throw new Error(
+    "Could not discover or provision a Google Cloud project. " +
+      "Try setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID environment variable. " +
+      "See https://goo.gle/gemini-cli-auth-docs#workspace-gca",
+  );
+}
+
+/**
+ * Get user email from the access token
+ */
+async function getUserEmail(accessToken: string): Promise<string | undefined> {
+  try {
+    const response = await fetch(
+      "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+      {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+        },
+      },
+    );
+
+    if (response.ok) {
+      const data = (await response.json()) as { email?: string };
+      return data.email;
+    }
+  } catch {
+    // Ignore errors, email is optional
+  }
+  return undefined;
+}
+
+/**
+ * Refresh Google Cloud Code Assist token
+ */
+export async function refreshGoogleCloudToken(
+  refreshToken: string,
+  projectId: string,
+): Promise<OAuthCredentials> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      refresh_token: refreshToken,
+      grant_type: "refresh_token",
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Google Cloud token refresh failed: ${error}`);
+  }
+
+  const data = (await response.json()) as {
+    access_token: string;
+    expires_in: number;
+    refresh_token?: string;
+  };
+
+  return {
+    refresh: data.refresh_token || refreshToken,
+    access: data.access_token,
+    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
+    projectId,
+  };
+}
+
+/**
+ * Login with Gemini CLI (Google Cloud Code Assist) OAuth
+ *
+ * @param onAuth - Callback with URL and optional instructions
+ * @param onProgress - Optional progress callback
+ * @param onManualCodeInput - Optional promise that resolves with user-pasted redirect URL.
+ *                            Races with browser callback - whichever completes first wins.
+ */
+export async function loginGeminiCli(
+  onAuth: (info: { url: string; instructions?: string }) => void,
+  onProgress?: (message: string) => void,
+  onManualCodeInput?: () => Promise<string>,
+): Promise<OAuthCredentials> {
+  const { verifier, challenge } = await generatePKCE();
+
+  // Start local server for callback
+  onProgress?.("Starting local server for OAuth callback...");
+  const server = await startCallbackServer();
+
+  let code: string | undefined;
+
+  try {
+    // Build authorization URL
+    const authParams = new URLSearchParams({
+      client_id: CLIENT_ID,
+      response_type: "code",
+      redirect_uri: REDIRECT_URI,
+      scope: SCOPES.join(" "),
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      state: verifier,
+      access_type: "offline",
+      prompt: "consent",
+    });
+
+    const authUrl = `${AUTH_URL}?${authParams.toString()}`;
+
+    // Notify caller with URL to open
+    onAuth({
+      url: authUrl,
+      instructions: "Complete the sign-in in your browser.",
+    });
+
+    // Wait for the callback, racing with manual input if provided
+    onProgress?.("Waiting for OAuth callback...");
+
+    if (onManualCodeInput) {
+      // Race between browser callback and manual input
+      let manualInput: string | undefined;
+      let manualError: Error | undefined;
+      const manualPromise = onManualCodeInput()
+        .then((input) => {
+          manualInput = input;
+          server.cancelWait();
+        })
+        .catch((err) => {
+          manualError = err instanceof Error ? err : new Error(String(err));
+          server.cancelWait();
+        });
+
+      const result = await server.waitForCode();
+
+      // If manual input was cancelled, throw that error
+      if (manualError) {
+        throw manualError;
+      }
+
+      if (result?.code) {
+        // Browser callback won - verify state
+        if (result.state !== verifier) {
+          throw new Error("OAuth state mismatch - possible CSRF attack");
+        }
+        code = result.code;
+      } else if (manualInput) {
+        // Manual input won
+        const parsed = parseRedirectUrl(manualInput);
+        if (parsed.state && parsed.state !== verifier) {
+          throw new Error("OAuth state mismatch - possible CSRF attack");
+        }
+        code = parsed.code;
+      }
+
+      // If still no code, wait for manual promise and try that
+      if (!code) {
+        await manualPromise;
+        if (manualError) {
+          throw manualError;
+        }
+        if (manualInput) {
+          const parsed = parseRedirectUrl(manualInput);
+          if (parsed.state && parsed.state !== verifier) {
+            throw new Error("OAuth state mismatch - possible CSRF attack");
+          }
+          code = parsed.code;
+        }
+      }
+    } else {
+      // Original flow: just wait for callback
+      const result = await server.waitForCode();
+      if (result?.code) {
+        if (result.state !== verifier) {
+          throw new Error("OAuth state mismatch - possible CSRF attack");
+        }
+        code = result.code;
+      }
+    }
+
+    if (!code) {
+      throw new Error("No authorization code received");
+    }
+
+    // Exchange code for tokens
+    onProgress?.("Exchanging authorization code for tokens...");
+    const tokenResponse = await fetch(TOKEN_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        client_id: CLIENT_ID,
+        client_secret: CLIENT_SECRET,
+        code,
+        grant_type: "authorization_code",
+        redirect_uri: REDIRECT_URI,
+        code_verifier: verifier,
+      }),
+    });
+
+    if (!tokenResponse.ok) {
+      const error = await tokenResponse.text();
+      throw new Error(`Token exchange failed: ${error}`);
+    }
+
+    const tokenData = (await tokenResponse.json()) as {
+      access_token: string;
+      refresh_token: string;
+      expires_in: number;
+    };
+
+    if (!tokenData.refresh_token) {
+      throw new Error("No refresh token received. Please try again.");
+    }
+
+    // Get user email
+    onProgress?.("Getting user info...");
+    const email = await getUserEmail(tokenData.access_token);
+
+    // Discover project
+    const projectId = await discoverProject(tokenData.access_token, onProgress);
+
+    // Calculate expiry time (current time + expires_in seconds - 5 min buffer)
+    const expiresAt = Date.now() + tokenData.expires_in * 1000 - 5 * 60 * 1000;
+
+    const credentials: OAuthCredentials = {
+      refresh: tokenData.refresh_token,
+      access: tokenData.access_token,
+      expires: expiresAt,
+      projectId,
+      email,
+    };
+
+    return credentials;
+  } finally {
+    server.server.close();
+  }
+}
+
+export const geminiCliOAuthProvider: OAuthProviderInterface = {
+  id: "google-gemini-cli",
+  name: "Google Cloud Code Assist (Gemini CLI)",
+  usesCallbackServer: true,
+
+  async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+    return loginGeminiCli(
+      callbacks.onAuth,
+      callbacks.onProgress,
+      callbacks.onManualCodeInput,
+    );
+  },
+
+  async refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+    const creds = credentials as GeminiCredentials;
+    if (!creds.projectId) {
+      throw new Error("Google Cloud credentials missing projectId");
+    }
+    return refreshGoogleCloudToken(creds.refresh, creds.projectId);
+  },
+
+  getApiKey(credentials: OAuthCredentials): string {
+    const creds = credentials as GeminiCredentials;
+    return JSON.stringify({ token: creds.access, projectId: creds.projectId });
+  },
+};

packages/ai/src/utils/oauth/index.ts

@@ -0,0 +1,187 @@
+/**
+ * OAuth credential management for AI providers.
+ *
+ * This module handles login, token refresh, and credential storage
+ * for OAuth-based providers:
+ * - Anthropic (Claude Pro/Max)
+ * - GitHub Copilot
+ * - Google Cloud Code Assist (Gemini CLI)
+ * - Antigravity (Gemini 3, Claude, GPT-OSS via Google Cloud)
+ */
+
+// Anthropic
+export {
+  anthropicOAuthProvider,
+  loginAnthropic,
+  refreshAnthropicToken,
+} from "./anthropic.js";
+// GitHub Copilot
+export {
+  getGitHubCopilotBaseUrl,
+  githubCopilotOAuthProvider,
+  loginGitHubCopilot,
+  normalizeDomain,
+  refreshGitHubCopilotToken,
+} from "./github-copilot.js";
+// Google Antigravity
+export {
+  antigravityOAuthProvider,
+  loginAntigravity,
+  refreshAntigravityToken,
+} from "./google-antigravity.js";
+// Google Gemini CLI
+export {
+  geminiCliOAuthProvider,
+  loginGeminiCli,
+  refreshGoogleCloudToken,
+} from "./google-gemini-cli.js";
+// OpenAI Codex (ChatGPT OAuth)
+export {
+  loginOpenAICodex,
+  openaiCodexOAuthProvider,
+  refreshOpenAICodexToken,
+} from "./openai-codex.js";
+
+export * from "./types.js";
+
+// ============================================================================
+// Provider Registry
+// ============================================================================
+
+import { anthropicOAuthProvider } from "./anthropic.js";
+import { githubCopilotOAuthProvider } from "./github-copilot.js";
+import { antigravityOAuthProvider } from "./google-antigravity.js";
+import { geminiCliOAuthProvider } from "./google-gemini-cli.js";
+import { openaiCodexOAuthProvider } from "./openai-codex.js";
+import type {
+  OAuthCredentials,
+  OAuthProviderId,
+  OAuthProviderInfo,
+  OAuthProviderInterface,
+} from "./types.js";
+
+const BUILT_IN_OAUTH_PROVIDERS: OAuthProviderInterface[] = [
+  anthropicOAuthProvider,
+  githubCopilotOAuthProvider,
+  geminiCliOAuthProvider,
+  antigravityOAuthProvider,
+  openaiCodexOAuthProvider,
+];
+
+const oauthProviderRegistry = new Map<string, OAuthProviderInterface>(
+  BUILT_IN_OAUTH_PROVIDERS.map((provider) => [provider.id, provider]),
+);
+
+/**
+ * Get an OAuth provider by ID
+ */
+export function getOAuthProvider(
+  id: OAuthProviderId,
+): OAuthProviderInterface | undefined {
+  return oauthProviderRegistry.get(id);
+}
+
+/**
+ * Register a custom OAuth provider
+ */
+export function registerOAuthProvider(provider: OAuthProviderInterface): void {
+  oauthProviderRegistry.set(provider.id, provider);
+}
+
+/**
+ * Unregister an OAuth provider.
+ *
+ * If the provider is built-in, restores the built-in implementation.
+ * Custom providers are removed completely.
+ */
+export function unregisterOAuthProvider(id: string): void {
+  const builtInProvider = BUILT_IN_OAUTH_PROVIDERS.find(
+    (provider) => provider.id === id,
+  );
+  if (builtInProvider) {
+    oauthProviderRegistry.set(id, builtInProvider);
+    return;
+  }
+  oauthProviderRegistry.delete(id);
+}
+
+/**
+ * Reset OAuth providers to built-ins.
+ */
+export function resetOAuthProviders(): void {
+  oauthProviderRegistry.clear();
+  for (const provider of BUILT_IN_OAUTH_PROVIDERS) {
+    oauthProviderRegistry.set(provider.id, provider);
+  }
+}
+
+/**
+ * Get all registered OAuth providers
+ */
+export function getOAuthProviders(): OAuthProviderInterface[] {
+  return Array.from(oauthProviderRegistry.values());
+}
+
+/**
+ * @deprecated Use getOAuthProviders() which returns OAuthProviderInterface[]
+ */
+export function getOAuthProviderInfoList(): OAuthProviderInfo[] {
+  return getOAuthProviders().map((p) => ({
+    id: p.id,
+    name: p.name,
+    available: true,
+  }));
+}
+
+// ============================================================================
+// High-level API (uses provider registry)
+// ============================================================================
+
+/**
+ * Refresh token for any OAuth provider.
+ * @deprecated Use getOAuthProvider(id).refreshToken() instead
+ */
+export async function refreshOAuthToken(
+  providerId: OAuthProviderId,
+  credentials: OAuthCredentials,
+): Promise<OAuthCredentials> {
+  const provider = getOAuthProvider(providerId);
+  if (!provider) {
+    throw new Error(`Unknown OAuth provider: ${providerId}`);
+  }
+  return provider.refreshToken(credentials);
+}
+
+/**
+ * Get API key for a provider from OAuth credentials.
+ * Automatically refreshes expired tokens.
+ *
+ * @returns API key string and updated credentials, or null if no credentials
+ * @throws Error if refresh fails
+ */
+export async function getOAuthApiKey(
+  providerId: OAuthProviderId,
+  credentials: Record<string, OAuthCredentials>,
+): Promise<{ newCredentials: OAuthCredentials; apiKey: string } | null> {
+  const provider = getOAuthProvider(providerId);
+  if (!provider) {
+    throw new Error(`Unknown OAuth provider: ${providerId}`);
+  }
+
+  let creds = credentials[providerId];
+  if (!creds) {
+    return null;
+  }
+
+  // Refresh if expired
+  if (Date.now() >= creds.expires) {
+    try {
+      creds = await provider.refreshToken(creds);
+    } catch (_error) {
+      throw new Error(`Failed to refresh OAuth token for ${providerId}`);
+    }
+  }
+
+  const apiKey = provider.getApiKey(creds);
+  return { newCredentials: creds, apiKey };
+}

packages/ai/src/utils/oauth/openai-codex.ts

@@ -0,0 +1,499 @@
+/**
+ * OpenAI Codex (ChatGPT OAuth) flow
+ *
+ * NOTE: This module uses Node.js crypto and http for the OAuth callback.
+ * It is only intended for CLI use, not browser environments.
+ */
+
+// NEVER convert to top-level imports - breaks browser/Vite builds (web-ui)
+let _randomBytes: typeof import("node:crypto").randomBytes | null = null;
+let _http: typeof import("node:http") | null = null;
+if (
+  typeof process !== "undefined" &&
+  (process.versions?.node || process.versions?.bun)
+) {
+  import("node:crypto").then((m) => {
+    _randomBytes = m.randomBytes;
+  });
+  import("node:http").then((m) => {
+    _http = m;
+  });
+}
+
+import { generatePKCE } from "./pkce.js";
+import type {
+  OAuthCredentials,
+  OAuthLoginCallbacks,
+  OAuthPrompt,
+  OAuthProviderInterface,
+} from "./types.js";
+
+const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize";
+const TOKEN_URL = "https://auth.openai.com/oauth/token";
+const REDIRECT_URI = "http://localhost:1455/auth/callback";
+const SCOPE = "openid profile email offline_access";
+const JWT_CLAIM_PATH = "https://api.openai.com/auth";
+
+const SUCCESS_HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Authentication successful</title>
+</head>
+<body>
+  <p>Authentication successful. Return to your terminal to continue.</p>
+</body>
+</html>`;
+
+type TokenSuccess = {
+  type: "success";
+  access: string;
+  refresh: string;
+  expires: number;
+};
+type TokenFailure = { type: "failed" };
+type TokenResult = TokenSuccess | TokenFailure;
+
+type JwtPayload = {
+  [JWT_CLAIM_PATH]?: {
+    chatgpt_account_id?: string;
+  };
+  [key: string]: unknown;
+};
+
+function createState(): string {
+  if (!_randomBytes) {
+    throw new Error(
+      "OpenAI Codex OAuth is only available in Node.js environments",
+    );
+  }
+  return _randomBytes(16).toString("hex");
+}
+
+function parseAuthorizationInput(input: string): {
+  code?: string;
+  state?: string;
+} {
+  const value = input.trim();
+  if (!value) return {};
+
+  try {
+    const url = new URL(value);
+    return {
+      code: url.searchParams.get("code") ?? undefined,
+      state: url.searchParams.get("state") ?? undefined,
+    };
+  } catch {
+    // not a URL
+  }
+
+  if (value.includes("#")) {
+    const [code, state] = value.split("#", 2);
+    return { code, state };
+  }
+
+  if (value.includes("code=")) {
+    const params = new URLSearchParams(value);
+    return {
+      code: params.get("code") ?? undefined,
+      state: params.get("state") ?? undefined,
+    };
+  }
+
+  return { code: value };
+}
+
+function decodeJwt(token: string): JwtPayload | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+    const payload = parts[1] ?? "";
+    const decoded = atob(payload);
+    return JSON.parse(decoded) as JwtPayload;
+  } catch {
+    return null;
+  }
+}
+
+async function exchangeAuthorizationCode(
+  code: string,
+  verifier: string,
+  redirectUri: string = REDIRECT_URI,
+): Promise<TokenResult> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      client_id: CLIENT_ID,
+      code,
+      code_verifier: verifier,
+      redirect_uri: redirectUri,
+    }),
+  });
+
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    console.error("[openai-codex] code->token failed:", response.status, text);
+    return { type: "failed" };
+  }
+
+  const json = (await response.json()) as {
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+  };
+
+  if (
+    !json.access_token ||
+    !json.refresh_token ||
+    typeof json.expires_in !== "number"
+  ) {
+    console.error("[openai-codex] token response missing fields:", json);
+    return { type: "failed" };
+  }
+
+  return {
+    type: "success",
+    access: json.access_token,
+    refresh: json.refresh_token,
+    expires: Date.now() + json.expires_in * 1000,
+  };
+}
+
+async function refreshAccessToken(refreshToken: string): Promise<TokenResult> {
+  try {
+    const response = await fetch(TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: CLIENT_ID,
+      }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      console.error(
+        "[openai-codex] Token refresh failed:",
+        response.status,
+        text,
+      );
+      return { type: "failed" };
+    }
+
+    const json = (await response.json()) as {
+      access_token?: string;
+      refresh_token?: string;
+      expires_in?: number;
+    };
+
+    if (
+      !json.access_token ||
+      !json.refresh_token ||
+      typeof json.expires_in !== "number"
+    ) {
+      console.error(
+        "[openai-codex] Token refresh response missing fields:",
+        json,
+      );
+      return { type: "failed" };
+    }
+
+    return {
+      type: "success",
+      access: json.access_token,
+      refresh: json.refresh_token,
+      expires: Date.now() + json.expires_in * 1000,
+    };
+  } catch (error) {
+    console.error("[openai-codex] Token refresh error:", error);
+    return { type: "failed" };
+  }
+}
+
+async function createAuthorizationFlow(
+  originator: string = "pi",
+): Promise<{ verifier: string; state: string; url: string }> {
+  const { verifier, challenge } = await generatePKCE();
+  const state = createState();
+
+  const url = new URL(AUTHORIZE_URL);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("redirect_uri", REDIRECT_URI);
+  url.searchParams.set("scope", SCOPE);
+  url.searchParams.set("code_challenge", challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", state);
+  url.searchParams.set("id_token_add_organizations", "true");
+  url.searchParams.set("codex_cli_simplified_flow", "true");
+  url.searchParams.set("originator", originator);
+
+  return { verifier, state, url: url.toString() };
+}
+
+type OAuthServerInfo = {
+  close: () => void;
+  cancelWait: () => void;
+  waitForCode: () => Promise<{ code: string } | null>;
+};
+
+function startLocalOAuthServer(state: string): Promise<OAuthServerInfo> {
+  if (!_http) {
+    throw new Error(
+      "OpenAI Codex OAuth is only available in Node.js environments",
+    );
+  }
+  let lastCode: string | null = null;
+  let cancelled = false;
+  const server = _http.createServer((req, res) => {
+    try {
+      const url = new URL(req.url || "", "http://localhost");
+      if (url.pathname !== "/auth/callback") {
+        res.statusCode = 404;
+        res.end("Not found");
+        return;
+      }
+      if (url.searchParams.get("state") !== state) {
+        res.statusCode = 400;
+        res.end("State mismatch");
+        return;
+      }
+      const code = url.searchParams.get("code");
+      if (!code) {
+        res.statusCode = 400;
+        res.end("Missing authorization code");
+        return;
+      }
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(SUCCESS_HTML);
+      lastCode = code;
+    } catch {
+      res.statusCode = 500;
+      res.end("Internal error");
+    }
+  });
+
+  return new Promise((resolve) => {
+    server
+      .listen(1455, "127.0.0.1", () => {
+        resolve({
+          close: () => server.close(),
+          cancelWait: () => {
+            cancelled = true;
+          },
+          waitForCode: async () => {
+            const sleep = () => new Promise((r) => setTimeout(r, 100));
+            for (let i = 0; i < 600; i += 1) {
+              if (lastCode) return { code: lastCode };
+              if (cancelled) return null;
+              await sleep();
+            }
+            return null;
+          },
+        });
+      })
+      .on("error", (err: NodeJS.ErrnoException) => {
+        console.error(
+          "[openai-codex] Failed to bind http://127.0.0.1:1455 (",
+          err.code,
+          ") Falling back to manual paste.",
+        );
+        resolve({
+          close: () => {
+            try {
+              server.close();
+            } catch {
+              // ignore
+            }
+          },
+          cancelWait: () => {},
+          waitForCode: async () => null,
+        });
+      });
+  });
+}
+
+function getAccountId(accessToken: string): string | null {
+  const payload = decodeJwt(accessToken);
+  const auth = payload?.[JWT_CLAIM_PATH];
+  const accountId = auth?.chatgpt_account_id;
+  return typeof accountId === "string" && accountId.length > 0
+    ? accountId
+    : null;
+}
+
+/**
+ * Login with OpenAI Codex OAuth
+ *
+ * @param options.onAuth - Called with URL and instructions when auth starts
+ * @param options.onPrompt - Called to prompt user for manual code paste (fallback if no onManualCodeInput)
+ * @param options.onProgress - Optional progress messages
+ * @param options.onManualCodeInput - Optional promise that resolves with user-pasted code.
+ *                                    Races with browser callback - whichever completes first wins.
+ *                                    Useful for showing paste input immediately alongside browser flow.
+ * @param options.originator - OAuth originator parameter (defaults to "pi")
+ */
+export async function loginOpenAICodex(options: {
+  onAuth: (info: { url: string; instructions?: string }) => void;
+  onPrompt: (prompt: OAuthPrompt) => Promise<string>;
+  onProgress?: (message: string) => void;
+  onManualCodeInput?: () => Promise<string>;
+  originator?: string;
+}): Promise<OAuthCredentials> {
+  const { verifier, state, url } = await createAuthorizationFlow(
+    options.originator,
+  );
+  const server = await startLocalOAuthServer(state);
+
+  options.onAuth({
+    url,
+    instructions: "A browser window should open. Complete login to finish.",
+  });
+
+  let code: string | undefined;
+  try {
+    if (options.onManualCodeInput) {
+      // Race between browser callback and manual input
+      let manualCode: string | undefined;
+      let manualError: Error | undefined;
+      const manualPromise = options
+        .onManualCodeInput()
+        .then((input) => {
+          manualCode = input;
+          server.cancelWait();
+        })
+        .catch((err) => {
+          manualError = err instanceof Error ? err : new Error(String(err));
+          server.cancelWait();
+        });
+
+      const result = await server.waitForCode();
+
+      // If manual input was cancelled, throw that error
+      if (manualError) {
+        throw manualError;
+      }
+
+      if (result?.code) {
+        // Browser callback won
+        code = result.code;
+      } else if (manualCode) {
+        // Manual input won (or callback timed out and user had entered code)
+        const parsed = parseAuthorizationInput(manualCode);
+        if (parsed.state && parsed.state !== state) {
+          throw new Error("State mismatch");
+        }
+        code = parsed.code;
+      }
+
+      // If still no code, wait for manual promise to complete and try that
+      if (!code) {
+        await manualPromise;
+        if (manualError) {
+          throw manualError;
+        }
+        if (manualCode) {
+          const parsed = parseAuthorizationInput(manualCode);
+          if (parsed.state && parsed.state !== state) {
+            throw new Error("State mismatch");
+          }
+          code = parsed.code;
+        }
+      }
+    } else {
+      // Original flow: wait for callback, then prompt if needed
+      const result = await server.waitForCode();
+      if (result?.code) {
+        code = result.code;
+      }
+    }
+
+    // Fallback to onPrompt if still no code
+    if (!code) {
+      const input = await options.onPrompt({
+        message: "Paste the authorization code (or full redirect URL):",
+      });
+      const parsed = parseAuthorizationInput(input);
+      if (parsed.state && parsed.state !== state) {
+        throw new Error("State mismatch");
+      }
+      code = parsed.code;
+    }
+
+    if (!code) {
+      throw new Error("Missing authorization code");
+    }
+
+    const tokenResult = await exchangeAuthorizationCode(code, verifier);
+    if (tokenResult.type !== "success") {
+      throw new Error("Token exchange failed");
+    }
+
+    const accountId = getAccountId(tokenResult.access);
+    if (!accountId) {
+      throw new Error("Failed to extract accountId from token");
+    }
+
+    return {
+      access: tokenResult.access,
+      refresh: tokenResult.refresh,
+      expires: tokenResult.expires,
+      accountId,
+    };
+  } finally {
+    server.close();
+  }
+}
+
+/**
+ * Refresh OpenAI Codex OAuth token
+ */
+export async function refreshOpenAICodexToken(
+  refreshToken: string,
+): Promise<OAuthCredentials> {
+  const result = await refreshAccessToken(refreshToken);
+  if (result.type !== "success") {
+    throw new Error("Failed to refresh OpenAI Codex token");
+  }
+
+  const accountId = getAccountId(result.access);
+  if (!accountId) {
+    throw new Error("Failed to extract accountId from token");
+  }
+
+  return {
+    access: result.access,
+    refresh: result.refresh,
+    expires: result.expires,
+    accountId,
+  };
+}
+
+export const openaiCodexOAuthProvider: OAuthProviderInterface = {
+  id: "openai-codex",
+  name: "ChatGPT Plus/Pro (Codex Subscription)",
+  usesCallbackServer: true,
+
+  async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+    return loginOpenAICodex({
+      onAuth: callbacks.onAuth,
+      onPrompt: callbacks.onPrompt,
+      onProgress: callbacks.onProgress,
+      onManualCodeInput: callbacks.onManualCodeInput,
+    });
+  },
+
+  async refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+    return refreshOpenAICodexToken(credentials.refresh);
+  },
+
+  getApiKey(credentials: OAuthCredentials): string {
+    return credentials.access;
+  },
+};

packages/ai/src/utils/oauth/pkce.ts

@@ -0,0 +1,37 @@
+/**
+ * PKCE utilities using Web Crypto API.
+ * Works in both Node.js 20+ and browsers.
+ */
+
+/**
+ * Encode bytes as base64url string.
+ */
+function base64urlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+/**
+ * Generate PKCE code verifier and challenge.
+ * Uses Web Crypto API for cross-platform compatibility.
+ */
+export async function generatePKCE(): Promise<{
+  verifier: string;
+  challenge: string;
+}> {
+  // Generate random verifier
+  const verifierBytes = new Uint8Array(32);
+  crypto.getRandomValues(verifierBytes);
+  const verifier = base64urlEncode(verifierBytes);
+
+  // Compute SHA-256 challenge
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const challenge = base64urlEncode(new Uint8Array(hashBuffer));
+
+  return { verifier, challenge };
+}

packages/ai/src/utils/oauth/types.ts

@@ -0,0 +1,62 @@
+import type { Api, Model } from "../../types.js";
+
+export type OAuthCredentials = {
+  refresh: string;
+  access: string;
+  expires: number;
+  [key: string]: unknown;
+};
+
+export type OAuthProviderId = string;
+
+/** @deprecated Use OAuthProviderId instead */
+export type OAuthProvider = OAuthProviderId;
+
+export type OAuthPrompt = {
+  message: string;
+  placeholder?: string;
+  allowEmpty?: boolean;
+};
+
+export type OAuthAuthInfo = {
+  url: string;
+  instructions?: string;
+};
+
+export interface OAuthLoginCallbacks {
+  onAuth: (info: OAuthAuthInfo) => void;
+  onPrompt: (prompt: OAuthPrompt) => Promise<string>;
+  onProgress?: (message: string) => void;
+  onManualCodeInput?: () => Promise<string>;
+  signal?: AbortSignal;
+}
+
+export interface OAuthProviderInterface {
+  readonly id: OAuthProviderId;
+  readonly name: string;
+
+  /** Run the login flow, return credentials to persist */
+  login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+
+  /** Whether login uses a local callback server and supports manual code input. */
+  usesCallbackServer?: boolean;
+
+  /** Refresh expired credentials, return updated credentials to persist */
+  refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+
+  /** Convert credentials to API key string for the provider */
+  getApiKey(credentials: OAuthCredentials): string;
+
+  /** Optional: modify models for this provider (e.g., update baseUrl) */
+  modifyModels?(
+    models: Model<Api>[],
+    credentials: OAuthCredentials,
+  ): Model<Api>[];
+}
+
+/** @deprecated Use OAuthProviderInterface instead */
+export interface OAuthProviderInfo {
+  id: OAuthProviderId;
+  name: string;
+  available: boolean;
+}

packages/ai/src/utils/overflow.ts

@@ -0,0 +1,127 @@
+import type { AssistantMessage } from "../types.js";
+
+/**
+ * Regex patterns to detect context overflow errors from different providers.
+ *
+ * These patterns match error messages returned when the input exceeds
+ * the model's context window.
+ *
+ * Provider-specific patterns (with example error messages):
+ *
+ * - Anthropic: "prompt is too long: 213462 tokens > 200000 maximum"
+ * - OpenAI: "Your input exceeds the context window of this model"
+ * - Google: "The input token count (1196265) exceeds the maximum number of tokens allowed (1048575)"
+ * - xAI: "This model's maximum prompt length is 131072 but the request contains 537812 tokens"
+ * - Groq: "Please reduce the length of the messages or completion"
+ * - OpenRouter: "This endpoint's maximum context length is X tokens. However, you requested about Y tokens"
+ * - llama.cpp: "the request exceeds the available context size, try increasing it"
+ * - LM Studio: "tokens to keep from the initial prompt is greater than the context length"
+ * - GitHub Copilot: "prompt token count of X exceeds the limit of Y"
+ * - MiniMax: "invalid params, context window exceeds limit"
+ * - Kimi For Coding: "Your request exceeded model token limit: X (requested: Y)"
+ * - Cerebras: Returns "400/413 status code (no body)" - handled separately below
+ * - Mistral: "Prompt contains X tokens ... too large for model with Y maximum context length"
+ * - z.ai: Does NOT error, accepts overflow silently - handled via usage.input > contextWindow
+ * - Ollama: Silently truncates input - not detectable via error message
+ */
+const OVERFLOW_PATTERNS = [
+  /prompt is too long/i, // Anthropic
+  /input is too long for requested model/i, // Amazon Bedrock
+  /exceeds the context window/i, // OpenAI (Completions & Responses API)
+  /input token count.*exceeds the maximum/i, // Google (Gemini)
+  /maximum prompt length is \d+/i, // xAI (Grok)
+  /reduce the length of the messages/i, // Groq
+  /maximum context length is \d+ tokens/i, // OpenRouter (all backends)
+  /exceeds the limit of \d+/i, // GitHub Copilot
+  /exceeds the available context size/i, // llama.cpp server
+  /greater than the context length/i, // LM Studio
+  /context window exceeds limit/i, // MiniMax
+  /exceeded model token limit/i, // Kimi For Coding
+  /too large for model with \d+ maximum context length/i, // Mistral
+  /context[_ ]length[_ ]exceeded/i, // Generic fallback
+  /too many tokens/i, // Generic fallback
+  /token limit exceeded/i, // Generic fallback
+];
+
+/**
+ * Check if an assistant message represents a context overflow error.
+ *
+ * This handles two cases:
+ * 1. Error-based overflow: Most providers return stopReason "error" with a
+ *    specific error message pattern.
+ * 2. Silent overflow: Some providers accept overflow requests and return
+ *    successfully. For these, we check if usage.input exceeds the context window.
+ *
+ * ## Reliability by Provider
+ *
+ * **Reliable detection (returns error with detectable message):**
+ * - Anthropic: "prompt is too long: X tokens > Y maximum"
+ * - OpenAI (Completions & Responses): "exceeds the context window"
+ * - Google Gemini: "input token count exceeds the maximum"
+ * - xAI (Grok): "maximum prompt length is X but request contains Y"
+ * - Groq: "reduce the length of the messages"
+ * - Cerebras: 400/413 status code (no body)
+ * - Mistral: "Prompt contains X tokens ... too large for model with Y maximum context length"
+ * - OpenRouter (all backends): "maximum context length is X tokens"
+ * - llama.cpp: "exceeds the available context size"
+ * - LM Studio: "greater than the context length"
+ * - Kimi For Coding: "exceeded model token limit: X (requested: Y)"
+ *
+ * **Unreliable detection:**
+ * - z.ai: Sometimes accepts overflow silently (detectable via usage.input > contextWindow),
+ *   sometimes returns rate limit errors. Pass contextWindow param to detect silent overflow.
+ * - Ollama: Silently truncates input without error. Cannot be detected via this function.
+ *   The response will have usage.input < expected, but we don't know the expected value.
+ *
+ * ## Custom Providers
+ *
+ * If you've added custom models via settings.json, this function may not detect
+ * overflow errors from those providers. To add support:
+ *
+ * 1. Send a request that exceeds the model's context window
+ * 2. Check the errorMessage in the response
+ * 3. Create a regex pattern that matches the error
+ * 4. The pattern should be added to OVERFLOW_PATTERNS in this file, or
+ *    check the errorMessage yourself before calling this function
+ *
+ * @param message - The assistant message to check
+ * @param contextWindow - Optional context window size for detecting silent overflow (z.ai)
+ * @returns true if the message indicates a context overflow
+ */
+export function isContextOverflow(
+  message: AssistantMessage,
+  contextWindow?: number,
+): boolean {
+  // Case 1: Check error message patterns
+  if (message.stopReason === "error" && message.errorMessage) {
+    // Check known patterns
+    if (OVERFLOW_PATTERNS.some((p) => p.test(message.errorMessage!))) {
+      return true;
+    }
+
+    // Cerebras returns 400/413 with no body for context overflow
+    // Note: 429 is rate limiting (requests/tokens per time), NOT context overflow
+    if (
+      /^4(00|13)\s*(status code)?\s*\(no body\)/i.test(message.errorMessage)
+    ) {
+      return true;
+    }
+  }
+
+  // Case 2: Silent overflow (z.ai style) - successful but usage exceeds context
+  if (contextWindow && message.stopReason === "stop") {
+    const inputTokens = message.usage.input + message.usage.cacheRead;
+    if (inputTokens > contextWindow) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Get the overflow patterns for testing purposes.
+ */
+export function getOverflowPatterns(): RegExp[] {
+  return [...OVERFLOW_PATTERNS];
+}

packages/ai/src/utils/sanitize-unicode.ts

@@ -0,0 +1,28 @@
+/**
+ * Removes unpaired Unicode surrogate characters from a string.
+ *
+ * Unpaired surrogates (high surrogates 0xD800-0xDBFF without matching low surrogates 0xDC00-0xDFFF,
+ * or vice versa) cause JSON serialization errors in many API providers.
+ *
+ * Valid emoji and other characters outside the Basic Multilingual Plane use properly paired
+ * surrogates and will NOT be affected by this function.
+ *
+ * @param text - The text to sanitize
+ * @returns The sanitized text with unpaired surrogates removed
+ *
+ * @example
+ * // Valid emoji (properly paired surrogates) are preserved
+ * sanitizeSurrogates("Hello 🙈 World") // => "Hello 🙈 World"
+ *
+ * // Unpaired high surrogate is removed
+ * const unpaired = String.fromCharCode(0xD83D); // high surrogate without low
+ * sanitizeSurrogates(`Text ${unpaired} here`) // => "Text  here"
+ */
+export function sanitizeSurrogates(text: string): string {
+  // Replace unpaired high surrogates (0xD800-0xDBFF not followed by low surrogate)
+  // Replace unpaired low surrogates (0xDC00-0xDFFF not preceded by high surrogate)
+  return text.replace(
+    /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g,
+    "",
+  );
+}

packages/ai/src/utils/typebox-helpers.ts

@@ -0,0 +1,24 @@
+import { type TUnsafe, Type } from "@sinclair/typebox";
+
+/**
+ * Creates a string enum schema compatible with Google's API and other providers
+ * that don't support anyOf/const patterns.
+ *
+ * @example
+ * const OperationSchema = StringEnum(["add", "subtract", "multiply", "divide"], {
+ *   description: "The operation to perform"
+ * });
+ *
+ * type Operation = Static<typeof OperationSchema>; // "add" | "subtract" | "multiply" | "divide"
+ */
+export function StringEnum<T extends readonly string[]>(
+  values: T,
+  options?: { description?: string; default?: T[number] },
+): TUnsafe<T[number]> {
+  return Type.Unsafe<T[number]>({
+    type: "string",
+    enum: values as any,
+    ...(options?.description && { description: options.description }),
+    ...(options?.default && { default: options.default }),
+  });
+}

packages/ai/src/utils/validation.ts

@@ -0,0 +1,88 @@
+import AjvModule from "ajv";
+import addFormatsModule from "ajv-formats";
+
+// Handle both default and named exports
+const Ajv = (AjvModule as any).default || AjvModule;
+const addFormats = (addFormatsModule as any).default || addFormatsModule;
+
+import type { Tool, ToolCall } from "../types.js";
+
+// Detect if we're in a browser extension environment with strict CSP
+// Chrome extensions with Manifest V3 don't allow eval/Function constructor
+const isBrowserExtension =
+  typeof globalThis !== "undefined" &&
+  (globalThis as any).chrome?.runtime?.id !== undefined;
+
+// Create a singleton AJV instance with formats (only if not in browser extension)
+// AJV requires 'unsafe-eval' CSP which is not allowed in Manifest V3
+let ajv: any = null;
+if (!isBrowserExtension) {
+  try {
+    ajv = new Ajv({
+      allErrors: true,
+      strict: false,
+      coerceTypes: true,
+    });
+    addFormats(ajv);
+  } catch (_e) {
+    // AJV initialization failed (likely CSP restriction)
+    console.warn("AJV validation disabled due to CSP restrictions");
+  }
+}
+
+/**
+ * Finds a tool by name and validates the tool call arguments against its TypeBox schema
+ * @param tools Array of tool definitions
+ * @param toolCall The tool call from the LLM
+ * @returns The validated arguments
+ * @throws Error if tool is not found or validation fails
+ */
+export function validateToolCall(tools: Tool[], toolCall: ToolCall): any {
+  const tool = tools.find((t) => t.name === toolCall.name);
+  if (!tool) {
+    throw new Error(`Tool "${toolCall.name}" not found`);
+  }
+  return validateToolArguments(tool, toolCall);
+}
+
+/**
+ * Validates tool call arguments against the tool's TypeBox schema
+ * @param tool The tool definition with TypeBox schema
+ * @param toolCall The tool call from the LLM
+ * @returns The validated (and potentially coerced) arguments
+ * @throws Error with formatted message if validation fails
+ */
+export function validateToolArguments(tool: Tool, toolCall: ToolCall): any {
+  // Skip validation in browser extension environment (CSP restrictions prevent AJV from working)
+  if (!ajv || isBrowserExtension) {
+    // Trust the LLM's output without validation
+    // Browser extensions can't use AJV due to Manifest V3 CSP restrictions
+    return toolCall.arguments;
+  }
+
+  // Compile the schema
+  const validate = ajv.compile(tool.parameters);
+
+  // Clone arguments so AJV can safely mutate for type coercion
+  const args = structuredClone(toolCall.arguments);
+
+  // Validate the arguments (AJV mutates args in-place for type coercion)
+  if (validate(args)) {
+    return args;
+  }
+
+  // Format validation errors nicely
+  const errors =
+    validate.errors
+      ?.map((err: any) => {
+        const path = err.instancePath
+          ? err.instancePath.substring(1)
+          : err.params.missingProperty || "root";
+        return `  - ${path}: ${err.message}`;
+      })
+      .join("\n") || "Unknown validation error";
+
+  const errorMessage = `Validation failed for tool "${toolCall.name}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(toolCall.arguments, null, 2)}`;
+
+  throw new Error(errorMessage);
+}