@visual-z/xeno 0.2.1 → 0.4.0

package/src/runtime/model-discovery.ts

@@ -0,0 +1,208 @@
+/**
+ * Live model discovery: ask the provider which models this key can use.
+ *
+ * Wire vocabulary (URLs, auth headers, response shapes) belongs to runtime,
+ * not the SDK-free core (D13). Everything except `discoverModels` is pure so
+ * the URL and parsing rules are unit tested without a network.
+ *
+ * Endpoints, per the vendors' own list APIs and what magpie / CC Switch /
+ * Crush converged on (docs/tasks/feat-provider-connect.md):
+ *   OpenAI-compatible  GET {base}/models                Authorization: Bearer
+ *   Anthropic          GET {root}/v1/models             x-api-key + anthropic-version
+ *                      (paged: has_more / last_id → ?after_id=)
+ *   Gemini             GET {base}/models                x-goog-api-key
+ *                      (paged: nextPageToken → ?pageToken=; keep generateContent)
+ *
+ * A pasted full endpoint (…/chat/completions, …/v1/messages) is cut back to
+ * its base, and a base without a version segment also tries `/v1`, because
+ * gateways disagree on where the version lives. Anthropic-compatible
+ * gateways often want Bearer instead of x-api-key; both are sent (magpie).
+ */
+import type { ProviderApi } from "./provider-protocols.ts";
+
+export type DiscoveryFamily = "openai" | "anthropic" | "google";
+
+export interface DiscoveredModel {
+  id: string;
+  name?: string;
+  contextWindow?: number;
+  maxTokens?: number;
+}
+
+export type DiscoveryResult =
+  | { ok: true; models: DiscoveredModel[]; url: string }
+  | { ok: false; reason: string; status?: number };
+
+export function discoveryFamily(api: ProviderApi): DiscoveryFamily | undefined {
+  switch (api) {
+    case "openai-completions":
+    case "openai-responses":
+    case "mistral-conversations":
+      return "openai";
+    case "anthropic-messages":
+      return "anthropic";
+    case "google-generative-ai":
+      return "google";
+    default:
+      // Vertex, Bedrock, Azure, Codex and Pi need cloud auth or have no
+      // listing endpoint; their catalog entries stay authoritative.
+      return undefined;
+  }
+}
+
+const ENDPOINT_SUFFIXES = [/\/chat\/completions\/?$/, /\/responses\/?$/, /\/completions\/?$/, /\/messages\/?$/, /\/models\/?$/];
+
+/** Strip whitespace, trailing slashes and a pasted operation path. */
+export function normalizeBaseUrl(raw: string): string {
+  let url = raw.trim().replace(/\/+$/, "");
+  for (const suffix of ENDPOINT_SUFFIXES) url = url.replace(suffix, "");
+  return url.replace(/\/+$/, "");
+}
+
+const VERSIONED = /\/v\d+(beta\d*|alpha\d*)?$/;
+
+export function discoveryUrls(family: DiscoveryFamily, baseUrl: string): string[] {
+  const base = normalizeBaseUrl(baseUrl);
+  const urls: string[] = [];
+  const add = (url: string) => { if (!urls.includes(url)) urls.push(url); };
+  switch (family) {
+    case "openai":
+      add(`${base}/models`);
+      if (!VERSIONED.test(base)) add(`${base}/v1/models`);
+      break;
+    case "anthropic": {
+      const root = base.replace(/\/v1$/, "");
+      add(`${root}/v1/models`);
+      add(`${base}/models`);
+      break;
+    }
+    case "google":
+      add(VERSIONED.test(base) ? `${base}/models` : `${base}/v1beta/models`);
+      break;
+  }
+  return urls;
+}
+
+export function discoveryHeaders(family: DiscoveryFamily, key: string): Record<string, string> {
+  if (key.length === 0) return {};
+  switch (family) {
+    case "openai": return { authorization: `Bearer ${key}` };
+    case "anthropic": return { "x-api-key": key, authorization: `Bearer ${key}`, "anthropic-version": "2023-06-01" };
+    case "google": return { "x-goog-api-key": key };
+  }
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function positive(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+/** One page of a list response. `next` is the query to append for the following page. */
+export function parseModelPage(family: DiscoveryFamily, json: unknown): { models: DiscoveredModel[]; next?: string } {
+  if (!record(json)) return { models: [] };
+  const rows = Array.isArray(json["data"]) ? json["data"] : Array.isArray(json["models"]) ? json["models"] : [];
+  const models: DiscoveredModel[] = [];
+  for (const row of rows) {
+    if (!record(row)) continue;
+    if (family === "google") {
+      const methods = row["supportedGenerationMethods"];
+      if (Array.isArray(methods) && !methods.includes("generateContent")) continue;
+      const id = text(row["name"])?.replace(/^models\//, "") ?? text(row["id"]);
+      if (!id) continue;
+      models.push(compact({ id, name: text(row["displayName"]), contextWindow: positive(row["inputTokenLimit"]), maxTokens: positive(row["outputTokenLimit"]) }));
+      continue;
+    }
+    const id = text(row["id"]) ?? text(row["name"]);
+    if (!id) continue;
+    // OpenRouter and several gateways publish limits on the listing itself.
+    const top = record(row["top_provider"]) ? row["top_provider"] : {};
+    models.push(compact({
+      id,
+      name: text(row["display_name"]) ?? (text(row["name"]) !== id ? text(row["name"]) : undefined),
+      contextWindow: positive(row["context_length"]) ?? positive(row["context_window"]) ?? positive(top["context_length"]),
+      maxTokens: positive(row["max_output_tokens"]) ?? positive(top["max_completion_tokens"]),
+    }));
+  }
+  if (family === "anthropic" && json["has_more"] === true && text(json["last_id"])) return { models, next: `after_id=${encodeURIComponent(String(json["last_id"]))}` };
+  if (family === "google" && text(json["nextPageToken"])) return { models, next: `pageToken=${encodeURIComponent(String(json["nextPageToken"]))}` };
+  return { models };
+}
+
+function compact(model: { id: string; name: string | undefined; contextWindow: number | undefined; maxTokens: number | undefined }): DiscoveredModel {
+  return { id: model.id, ...(model.name !== undefined ? { name: model.name } : {}),
+    ...(model.contextWindow !== undefined ? { contextWindow: model.contextWindow } : {}),
+    ...(model.maxTokens !== undefined ? { maxTokens: model.maxTokens } : {}) };
+}
+
+/**
+ * `/models` on OpenAI-style endpoints also lists embeddings, speech, image and
+ * moderation models. They can never run a coding turn, so the picker should
+ * not offer them. Pattern list, not a guess per model: ids that match are
+ * still shown in the wizard under "other", just not preselected.
+ */
+const NON_CHAT = /(^|[-_/.:])(embed|embedding|embeddings|tts|whisper|transcribe|dall-e|dalle|moderation|image|imagen|audio|realtime|speech|rerank|reranker|search|veo|sora|davinci|babbage)([-_/.:]|\d|$)/i;
+export function likelyChatModel(id: string): boolean {
+  return !NON_CHAT.test(id);
+}
+
+/**
+ * Network IO. Candidates are tried in order; 404/405 moves on, an auth
+ * failure stops (another URL will not make a wrong key right), and any
+ * other failure is reported with the URL that produced it.
+ * Timeout 10s per request: assumed; long enough for a slow gateway's first
+ * response, short enough that a dead host is reported while the user waits.
+ */
+const DISCOVERY_TIMEOUT_MS = 10_000;
+/** Pagination bound: Anthropic pages at 20 by default; 25 pages covers every known list. Assumed. */
+const MAX_PAGES = 25;
+
+export async function discoverModels(opts: {
+  family: DiscoveryFamily;
+  baseUrl: string;
+  key: string;
+  headers?: Record<string, string>;
+  fetch: (input: string, init?: RequestInit) => Promise<Response>;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}): Promise<DiscoveryResult> {
+  const headers = { accept: "application/json", ...discoveryHeaders(opts.family, opts.key), ...opts.headers };
+  let last: DiscoveryResult = { ok: false, reason: "no discovery URL" };
+  for (const url of discoveryUrls(opts.family, opts.baseUrl)) {
+    const models: DiscoveredModel[] = [];
+    let query: string | undefined;
+    let failed: DiscoveryResult | undefined;
+    for (let page = 0; page < MAX_PAGES; page++) {
+      const target = query ? `${url}${url.includes("?") ? "&" : "?"}${query}` : url;
+      let response: Response;
+      try {
+        const timeout = AbortSignal.timeout(opts.timeoutMs ?? DISCOVERY_TIMEOUT_MS);
+        response = await opts.fetch(target, { headers, signal: opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout });
+      } catch (error) {
+        if (opts.signal?.aborted) return { ok: false, reason: "cancelled" };
+        failed = { ok: false, reason: `${url}: ${error instanceof Error && error.name === "TimeoutError" ? "timed out" : error instanceof Error ? error.message : String(error)}` };
+        break;
+      }
+      if (response.status === 401 || response.status === 403) {
+        return { ok: false, status: response.status, reason: `${url}: authentication failed (HTTP ${response.status}); check the API key` };
+      }
+      if (!response.ok) { failed = { ok: false, status: response.status, reason: `${url}: HTTP ${response.status}` }; break; }
+      let json: unknown;
+      try { json = await response.json(); } catch { failed = { ok: false, reason: `${url}: response is not JSON` }; break; }
+      const parsed = parseModelPage(opts.family, json);
+      models.push(...parsed.models);
+      if (!parsed.next) break;
+      query = parsed.next;
+    }
+    if (!failed && models.length > 0) {
+      const seen = new Set<string>();
+      return { ok: true, url, models: models.filter(model => !seen.has(model.id) && seen.add(model.id)) };
+    }
+    last = failed ?? { ok: false, reason: `${url}: the provider returned no models` };
+  }
+  return last;
+}

package/src/runtime/model.ts

@@ -19,6 +19,7 @@
 import type { ProviderApi } from "./provider-protocols.ts";
 import { SOURCE_MODELS } from "./model-data.ts";
 import { mergeCatalogs } from "../core/catalog-merge.ts";
+import { GROK_PROVIDER, GROK_BASE_URL } from "./oauth.ts";
 export type Api = ProviderApi;
 
 /** How hard the model should think. Capability and wire vocabulary are mapped per model. */
@@ -440,6 +441,14 @@ export const CURATED_CATALOG: readonly ModelSpec[] = [
   DEEPSEEK_V4_PRO,
   DEEPSEEK_FLASH,
 
+  {
+    id: "grok-build", name: "Grok Build", provider: GROK_PROVIDER, baseUrl: GROK_BASE_URL,
+    api: "openai-completions", driver: "pi", input: ["text"],
+    // The official proxy alias has no published effort/price contract. Do not copy API model rates.
+    reasoning: false,
+    nativeCompat: { supportsDeveloperRole: false, supportsReasoningEffort: false, maxTokensField: "max_tokens" },
+  },
+
   completionsModel({
     id: "grok-4.6",
   // Input modalities from the existing models.dev catalog source, 2026-09-30.

package/src/runtime/native-eval-fixtures.ts

@@ -0,0 +1,33 @@
+/** Q.20: a synthetic wire peer validates the native path without spending model quota. */
+import { nativeWire } from "./native-eval.ts";
+import { toolModeBackend } from "./tool-mode-eval.ts";
+import type { EvalFixture } from "./harness-eval.ts";
+
+export function nativeFixtureFetch(fixture: EvalFixture): typeof fetch {
+  const backend = toolModeBackend(fixture);
+  return (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const request = new Request(input, init), payload = await nativeWire(request);
+    const tools = payload["tools"] as { name: string; parameters: unknown }[];
+    const source = payload["input"] as Record<string, unknown>[];
+    const response = await backend({ tools: tools.map(tool => ({ function: tool })),
+      messages: source.filter(item => item["type"] === "function_call_output").map(item => ({ role: "tool", content: item["output"] })) }, request.signal) as {
+        id: string; choices: { message: { content: string | null; tool_calls?: { id: string; function: { name: string; arguments: string } }[] } }[] };
+    const message = response.choices[0]!.message, events: unknown[] = [], output: unknown[] = [];
+    for (const [index, call] of (message.tool_calls ?? []).entries()) {
+      const item = { type: "function_call", id: "fc_" + call.id, call_id: call.id, name: call.function.name, arguments: call.function.arguments, status: "completed" };
+      events.push({ type: "response.output_item.added", output_index: index, item: { ...item, arguments: "" } },
+        { type: "response.function_call_arguments.delta", output_index: index, delta: call.function.arguments },
+        { type: "response.output_item.done", output_index: index, item }); output.push(item);
+    }
+    if (message.content) {
+      const item = { type: "message", id: "msg_" + response.id, role: "assistant", content: [{ type: "output_text", text: message.content, annotations: [] }], status: "completed" };
+      events.push({ type: "response.output_item.added", output_index: 0, item: { ...item, content: [] } },
+        { type: "response.content_part.added", output_index: 0, content_index: 0, part: { type: "output_text", text: "", annotations: [] } },
+        { type: "response.output_text.delta", output_index: 0, content_index: 0, delta: message.content },
+        { type: "response.output_item.done", output_index: 0, item }); output.push(item);
+    }
+    events.push({ type: "response.completed", response: { id: response.id, model: "gpt-6-luna", status: "completed", output,
+      usage: { input_tokens: 200, output_tokens: 32, input_tokens_details: { cached_tokens: 50, cache_write_tokens: 20 }, total_tokens: 232 } } });
+    return new Response(events.map(event => "data: " + JSON.stringify(event) + "\n\n").join(""), { headers: { "content-type": "text/event-stream" } });
+  }) as typeof fetch;
+}

package/src/runtime/native-eval.ts

@@ -0,0 +1,146 @@
+/** Q.20: meter the production Responses adapter without translating its wire protocol. */
+import { createHash } from "node:crypto";
+import { nativeMeasured, nativeReservation, nativeUsage } from "../core/native-eval.ts";
+import type { BenchmarkPrice } from "../core/benchmark.ts";
+import type { FrozenPrefix, Message } from "../core/project.ts";
+import type { Provider, ProviderConfig } from "./provider.ts";
+import { PiProvider } from "./pi-provider.ts";
+import type { ComparisonLedger, GatewayRecord } from "./harness-comparison.ts";
+
+const digest = (body: string) => createHash("sha256").update(body).digest("hex");
+const bytes = (body: string) => new TextEncoder().encode(body);
+const noEffects = { env: () => undefined, run: () => { throw Error("evaluation forbids credential commands"); } };
+// Offline replay only. It has the SDK's required claim shape, no signature or authority.
+export const NATIVE_EVAL_TEST_KEY = "offline." + btoa(JSON.stringify({ "https://api.openai.com/auth": { chatgpt_account_id: "offline-evaluation" } })) + ".unsigned";
+
+export async function nativeWire(request: Request): Promise<Record<string, unknown>> {
+  const raw = new Uint8Array(await request.clone().arrayBuffer());
+  if (raw.length > 8 * 1024 * 1024) throw Error("native eval wire exceeds archive bound");
+  const body = request.headers.get("content-encoding") === "zstd" ? Bun.zstdDecompressSync(raw) : raw;
+  if (body.length > 8 * 1024 * 1024) throw Error("native eval wire exceeds archive bound");
+  return JSON.parse(new TextDecoder().decode(body)) as Record<string, unknown>;
+}
+/** Running the same serializer with a local fetch prevents a second, approximate wire builder. */
+export async function nativePayload(config: ProviderConfig, frozen: FrozenPrefix, messages: Message[], sessionId?: string): Promise<Record<string, unknown>> {
+  let payload: Record<string, unknown> | undefined;
+  const capture = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    payload = await nativeWire(new Request(input, init));
+    return new Response(null, { status: 400 });
+  }) as typeof fetch;
+  const provider = new PiProvider(config, NATIVE_EVAL_TEST_KEY, { oauth: true, effects: noEffects, fetch: capture,
+    ...(sessionId ? { sessionId } : {}), retry: { maxRetries: 0, maxRetryDelayMs: 0 } });
+  await provider.send(frozen, messages, 0).catch(() => {});
+  if (!payload) throw Error("native offline wire was not produced");
+  return payload;
+}
+export function nativeInput(payload: Record<string, unknown>): { bytes: Uint8Array; messages: unknown[] } {
+  if (!Array.isArray(payload["input"])) throw Error("native input is missing");
+  return { bytes: bytes(JSON.stringify([payload["instructions"], payload["tools"] ?? [], payload["input"]])), messages: payload["input"] };
+}
+export interface NativeResponse { model: unknown; usage: unknown; status: unknown; service_tier: unknown }
+
+/** Forward unchanged chunks with backpressure; retain only a terminal receipt, never headers. */
+export function nativeResponseTap(body: ReadableStream<Uint8Array>, terminal: (response: NativeResponse) => Promise<void>) {
+  const decoder = new TextDecoder(); let pending = "", observed = false;
+  const line = async (text: string) => {
+    if (!text.startsWith("data:") || text.slice(5).trim() === "[DONE]") return;
+    const event = JSON.parse(text.slice(5)) as Record<string, unknown>;
+    if (!["response.completed", "response.done", "response.incomplete"].includes(String(event["type"]))) return;
+    if (observed) throw Error("duplicate native terminal response");
+    observed = true;
+    const response = event["response"] as Record<string, unknown> | undefined;
+    await terminal({ model: response?.["model"] ?? null, usage: response?.["usage"] ?? null,
+      status: response?.["status"] ?? null, service_tier: response?.["service_tier"] ?? null });
+  };
+  return body.pipeThrough(new TransformStream<Uint8Array, Uint8Array>({
+    async transform(chunk, controller) {
+      pending += decoder.decode(chunk, { stream: true });
+      // The completed event repeats output. Bound this framing buffer separately from the saved receipt.
+      if (pending.length > 8 * 1024 * 1024) throw Error("native SSE frame exceeds archive bound");
+      let at: number;
+      while ((at = pending.indexOf("\n")) >= 0) { await line(pending.slice(0, at).replace(/\r$/, "")); pending = pending.slice(at + 1); }
+      controller.enqueue(chunk);
+    },
+    async flush() { pending += decoder.decode(); if (pending.trim()) await line(pending.trim()); },
+  }));
+}
+
+export function nativeEvalTransport(options: {
+  config: ProviderConfig; key: string; price: BenchmarkPrice; ledger: ComparisonLedger; maxRequests: number;
+  fetch?: typeof fetch;
+  sessionId?: string;
+  record: (row: GatewayRecord) => Promise<void>;
+  wire: (payload: Record<string, unknown>, request: number) => Promise<void>;
+  response: (receipt: NativeResponse, request: number) => Promise<void>;
+}) {
+  const { config, ledger, price } = options;
+  if (config.spec.api !== "openai-codex-responses" || !config.spec.maxTokens || config.maxTokens !== config.spec.maxTokens)
+    throw Error("native eval must reserve the full subscription model output ceiling");
+  const controller = new AbortController();
+  let requests = 0, stopped: "budget" | "balance" | "error" | "limit" | null = null;
+  let previous: ReturnType<typeof nativeInput> | null = null;
+  let current: { row: GatewayRecord; started: number; terminal: NativeResponse | null; httpStatus: number | null } | undefined;
+  let active = false, idle = Promise.resolve();
+  const observedFetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    if (!active || current || controller.signal.aborted || ledger.halted || stopped) throw Error("native eval refused an extra request");
+    if (requests >= options.maxRequests) { stopped = "limit"; throw Error("native request limit"); }
+    const request = new Request(input, init), payload = await nativeWire(request), wire = JSON.stringify(payload);
+    if (payload["model"] !== (config.spec.wireId ?? config.spec.id) || payload["store"] !== false || payload["previous_response_id"] !== undefined || payload["stream"] !== true)
+      throw Error("native wire differs from frozen stateless policy");
+    const reservation = nativeReservation(bytes(wire).length, config.spec.maxTokens!, price);
+    if (ledger.budget === null || ledger.charged + reservation > ledger.budget) { stopped = "budget"; throw Error("native eval budget exhausted"); }
+    const inputState = nativeInput(payload); let shared = 0;
+    if (previous) while (shared < Math.min(previous.bytes.length, inputState.bytes.length) && previous.bytes[shared] === inputState.bytes[shared]) shared++;
+    const unchanged = previous === null ? null : JSON.stringify(inputState.messages.slice(0, previous.messages.length)) === JSON.stringify(previous.messages);
+    previous = inputState;
+    ledger.charged += reservation;
+    const row: GatewayRecord = { kind: "reserved", request: ++requests, inputSha256: digest(wire), inputBytes: inputState.bytes.length,
+      sharedInputBytes: shared, prefixUnchanged: unchanged, hasTools: Array.isArray(payload["tools"]) && payload["tools"].length > 0,
+      reservation, charge: reservation, measured: null, ledgerCharged: ledger.charged, usage: null, failure: null, responseModel: null, wallMs: 0 };
+    const state = { row, started: performance.now(), terminal: null as NativeResponse | null, httpStatus: null as number | null };
+    current = state;
+    await options.record(row); await options.wire(payload, requests);
+    const response = await (options.fetch ?? fetch)(new Request(request, { redirect: "error", signal: AbortSignal.any([controller.signal, request.signal]) }));
+    state.httpStatus = response.status;
+    if (!response.ok || !response.body) { await response.body?.cancel(); throw Error("native upstream response failed"); }
+    return new Response(nativeResponseTap(response.body, async terminal => {
+      state.terminal = terminal; await options.response(terminal, row.request);
+    }), { status: response.status, headers: response.headers });
+  }) as typeof fetch;
+  const actual = new PiProvider(config, options.key, { oauth: true, effects: noEffects, fetch: observedFetch,
+    ...(options.sessionId ? { sessionId: options.sessionId } : {}), retry: { maxRetries: 0, maxRetryDelayMs: 0 } });
+  const provider: Provider = { config, async send(frozen, messages, node, signal, onDelta) {
+    if (active) throw Error("native eval model requests must be sequential");
+    active = true; current = undefined;
+    let finish = () => {}; idle = new Promise<void>(resolve => { finish = resolve; });
+    let failed = false;
+    try {
+      const turn = await actual.send(frozen, messages, node, AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]), onDelta);
+      const state = current as { terminal: NativeResponse | null } | undefined;
+      const observed = nativeUsage(state?.terminal);
+      const same = observed && Object.entries(observed).every(([key, count]) => turn.usage[key as keyof typeof observed] === count);
+      const model = state?.terminal?.model;
+      if (!same || typeof model !== "string" || !(model === config.spec.id || new RegExp("^" + config.spec.id + "-\\d{4}-\\d{2}-\\d{2}$").test(model)))
+        throw Error("native model or usage differs from the production adapter");
+      return turn;
+    } catch {
+      failed = true; stopped ??= "error";
+      throw Error("native eval request failed; inspect status and retained usage");
+    } finally {
+      try {
+        const state = current as { row: GatewayRecord; started: number; terminal: NativeResponse | null; httpStatus: number | null } | undefined;
+        if (state) {
+          const usage = nativeUsage(state.terminal), measured = nativeMeasured(state.terminal, price), charge = measured ?? state.row.reservation;
+          ledger.charged += charge - state.row.reservation;
+          if (failed || measured === null || charge > state.row.reservation) { ledger.halted = true; stopped ??= "error"; }
+          await options.record({ ...state.row, kind: "settled", usage, measured, charge, ledgerCharged: ledger.charged,
+            responseModel: typeof state.terminal?.model === "string" ? state.terminal.model : null,
+            failure: failed ? { kind: [402, 429].includes(state.httpStatus ?? 0) ? "balance" : "provider", status: state.httpStatus } : null,
+            wallMs: performance.now() - state.started });
+        }
+      } catch { ledger.halted = true; throw Error("native eval ledger could not be persisted"); }
+      finally { active = false; finish(); }
+    }
+  } };
+  return { provider, get requests() { return requests; }, get stopped() { return stopped; }, async close() { controller.abort(); await idle; } };
+}

package/src/runtime/oauth.ts

@@ -15,9 +15,10 @@
 
 import { createServer, type Server } from "node:http";
 import { pollDeviceCode } from "./oauth-device.ts";
+import { parseDeviceAuthorization, parseOAuthTokens } from "../core/oauth-fields.ts";
 
 /** Matches package.json. Sent as User-Agent so the server can see who we are (D18). */
-export const XENO_VERSION = "0.2.1";
+export const XENO_VERSION = "0.4.0";
 
 /**
  * Minutes subtracted from server expiry so a request issued at the edge
@@ -33,6 +34,7 @@ export const SUBSCRIPTION_OPTIONS = [
   { id: "claude-pro", provider: "anthropic", label: "Claude Pro/Max" },
   { id: "codex", provider: "openai-codex", label: "ChatGPT Plus/Pro (Codex)" },
   { id: "github-copilot", provider: "github-copilot", label: "GitHub Copilot" },
+  { id: "grok", provider: "xai-grok", label: "Grok (official account)" },
 ] as const;
 
 export type SubscriptionId = (typeof SUBSCRIPTION_OPTIONS)[number]["id"];
@@ -101,12 +103,83 @@ export const OPENAI_REDIRECT_URI = `http://localhost:${OPENAI_CALLBACK_PORT}${OP
 const OPENAI_SCOPE = "openid profile email offline_access";
 const OPENAI_JWT_CLAIM = "https://api.openai.com/auth";
 
+// Official Grok Build config.rs / device_code.rs, verified 2026-10-07.
+// This is the public first-party client, with xeno attribution retained (D18).
+const GROK_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+const GROK_AUTH_ORIGIN = "https://auth.x.ai";
+const GROK_TOKEN_URL = `${GROK_AUTH_ORIGIN}/oauth2/token`;
+// Only inference and refresh scopes: xeno does not store remote conversations/workspaces.
+const GROK_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+export const GROK_PROVIDER = "xai-grok";
+export const GROK_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+/** Official HTTP timeout: issuer requests cannot keep a cancelled or expired grant hanging indefinitely. */
+const GROK_REQUEST_TIMEOUT_MS = 15_000;
+
+async function grokPost(url: string, fields: Record<string, string>, effects: Pick<RefreshEffects, "fetch" | "signal">): Promise<{ status: number; json: unknown }> {
+  const timeout = AbortSignal.timeout(GROK_REQUEST_TIMEOUT_MS);
+  const signal = effects.signal ? AbortSignal.any([effects.signal, timeout]) : timeout;
+  try {
+    const response = await effects.fetch(url, { method: "POST", redirect: "error", signal,
+      headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json", "User-Agent": `xeno/${XENO_VERSION}` },
+      body: new URLSearchParams(fields) });
+    let json: unknown;
+    try { json = await response.json(); } catch { json = undefined; }
+    return { status: response.status, json };
+  } catch {
+    // Network errors can include request details; never expose a credential-bearing body.
+    throw new Error(effects.signal?.aborted ? "Login cancelled" : "Grok authentication request failed");
+  }
+}
+
+export async function loginGrok(interaction: OAuthInteraction, sleep?: Parameters<typeof pollDeviceCode>[0]["sleep"]): Promise<OAuthCredential> {
+  const started = await grokPost(`${GROK_AUTH_ORIGIN}/oauth2/device/code`,
+    { client_id: GROK_CLIENT_ID, scope: GROK_SCOPE, referrer: "xeno" }, interaction);
+  if (started.status < 200 || started.status >= 300) throw new Error(`Grok device code request failed (HTTP ${started.status})`);
+  const device = parseDeviceAuthorization(started.json, [GROK_AUTH_ORIGIN, "https://accounts.x.ai"]);
+  if (!device) throw new Error("Grok device code response was incomplete or untrusted");
+  interaction.signal.throwIfAborted();
+  const url = device.verificationUriComplete ?? device.verificationUri;
+  interaction.notify(`Open ${url}\nand enter code: ${device.userCode}`);
+  tryOpen(url, interaction.openBrowser);
+  return pollDeviceCode<OAuthCredential>({
+    expiresInSeconds: device.expiresIn, waitBeforeFirstPoll: true, signal: interaction.signal,
+    ...(device.interval !== undefined ? { intervalSeconds: device.interval } : {}), ...(sleep ? { sleep } : {}),
+    poll: async () => {
+      const got = await grokPost(GROK_TOKEN_URL,
+        { client_id: GROK_CLIENT_ID, device_code: device.deviceCode, grant_type: "urn:ietf:params:oauth:grant-type:device_code" }, interaction);
+      const body = asRecord(got.json);
+      // RFC 8628 errors use HTTP 400; they are polling states, never completed logins.
+      if (got.status === 400 && body?.["error"] === "authorization_pending") return { status: "pending" };
+      if (got.status === 400 && body?.["error"] === "slow_down") return { status: "slow_down" };
+      if (got.status < 200 || got.status >= 300) return { status: "failed", message: `Grok device login failed (HTTP ${got.status})` };
+      const fields = parseOAuthTokens(got.json);
+      if (!fields) return { status: "failed", message: "Grok token response was incomplete" };
+      interaction.signal.throwIfAborted();
+      return { status: "complete", value: { type: "oauth", access: fields.access, refresh: fields.refresh,
+        expires: expiryFromExpiresIn(fields.expiresIn, (interaction.now ?? Date.now)()) } };
+    },
+  });
+}
+
+async function refreshGrok(refresh: string, effects: RefreshEffects): Promise<{ ok: true; credential: OAuthCredential } | { ok: false; reason: string }> {
+  try {
+    const got = await grokPost(GROK_TOKEN_URL, { client_id: GROK_CLIENT_ID, grant_type: "refresh_token", refresh_token: refresh }, effects);
+    if (effects.signal?.aborted) return { ok: false, reason: "Login cancelled" };
+    if (got.status < 200 || got.status >= 300) return { ok: false, reason: `HTTP ${got.status}` };
+    const fields = parseOAuthTokens(got.json, refresh);
+    if (!fields) return { ok: false, reason: "unexpected body" };
+    return { ok: true, credential: { type: "oauth", access: fields.access, refresh: fields.refresh,
+      expires: expiryFromExpiresIn(fields.expiresIn, effects.now()) } };
+  } catch { return { ok: false, reason: "Grok token refresh failed" }; }
+}
+
 export function isSubscriptionLogin(id: string): boolean {
-  return SUBSCRIPTION_OPTIONS.some((o) => o.id === id);
+  return subscriptionById(id) !== undefined;
 }
 
 export function subscriptionById(id: string): (typeof SUBSCRIPTION_OPTIONS)[number] | undefined {
-  return SUBSCRIPTION_OPTIONS.find((o) => o.id === id);
+  // Separate account providers accept their catalog identity too; anthropic still means an API key.
+  return SUBSCRIPTION_OPTIONS.find(o => o.id === id || (o.provider === id && o.provider !== "anthropic"));
 }
 
 export function expiryFromExpiresIn(expiresIn: number, now: number): number {
@@ -505,6 +578,8 @@ export async function refreshOAuthCredential(
       return refreshOpenAI(credential.refresh, opts);
     case "github-copilot":
       return refreshCopilot(credential.refresh, opts, credential.enterpriseUrl);
+    case GROK_PROVIDER:
+      return refreshGrok(credential.refresh, opts);
     default:
       return { ok: false, reason: `no oauth refresh for ${provider}` };
   }
@@ -752,6 +827,8 @@ export async function loginSubscription(
       return { provider: "openai-codex", credential: await loginOpenAICodex(interaction) };
     case "github-copilot":
       return { provider: "github-copilot", credential: await loginGitHubCopilot(interaction) };
+    case "grok":
+      return { provider: GROK_PROVIDER, credential: await loginGrok(interaction) };
     default: {
       const never: never = id;
       throw new Error(`unknown subscription login: ${String(never)}`);