@shanepadgett/tau-agent 0.5.1 → 0.7.0

package/extensions/image-gen/index.ts

@@ -2,22 +2,21 @@ import { defineTool, withFileMutationQueue, type ExtensionAPI } from "@earendil-
 import { randomUUID } from "node:crypto";
 import { link, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { type Static, Type } from "typebox";
-import { editImage, generateImage, resolveCodexAuth, type EditImage } from "./client.ts";
+import { XAI_IMAGE_MODEL, XAI_PROVIDER } from "../xai/constants.ts";
+import { detectImageMimeType, editImage, generateImage, type EditImage, type GeneratedImage } from "./client.ts";
 
-const MODEL = "gpt-image-2";
 const MAX_INPUT_BYTES = 50 * 1024 * 1024;
 const MAX_INLINE_BYTES = 12 * 1024 * 1024;
-const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 
 const imageGenSchema = Type.Object(
 	{
 		prompt: Type.String({ minLength: 1 }),
 		path: Type.Optional(
-			Type.String({ description: "Explicit PNG destination path; defaults to Tau's external image store" }),
+			Type.String({ description: "Explicit image destination path; defaults to Tau's external image store" }),
 		),
-		referenced_image_paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 5 })),
+		referenced_image_paths: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: 3 })),
 	},
 	{ additionalProperties: false },
 );
@@ -26,23 +25,14 @@ type ImageGenParams = Static<typeof imageGenSchema>;
 
 interface ImageGenDetails {
 	path: string;
-	model: typeof MODEL;
+	model: typeof XAI_IMAGE_MODEL;
 	operation: "generate" | "edit";
 }
 
-function detectImageMimeType(bytes: Buffer): EditImage["mimeType"] | undefined {
-	if (bytes.length >= PNG_SIGNATURE.length && bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
-		return "image/png";
-	}
-	if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
-	if (
-		bytes.length >= 12 &&
-		bytes.subarray(0, 4).toString("ascii") === "RIFF" &&
-		bytes.subarray(8, 12).toString("ascii") === "WEBP"
-	) {
-		return "image/webp";
-	}
-	return undefined;
+function outputExtension(image: GeneratedImage): string {
+	if (image.mimeType === "image/png") return ".png";
+	if (image.mimeType === "image/webp") return ".webp";
+	return ".jpg";
 }
 
 export default function imageGenExtension(pi: ExtensionAPI): void {
@@ -51,12 +41,12 @@ export default function imageGenExtension(pi: ExtensionAPI): void {
 			name: "image_gen",
 			label: "Image Generation",
 			description:
-				"Generate a new raster image from a prompt, or edit one to five local raster images. Uses the existing OpenAI Codex OAuth login, saves a PNG under Tau's external image store unless an explicit path is provided, and returns the image for inspection.",
-			promptSnippet: "Generate or edit raster images with OpenAI Codex",
+				"Generate a new raster image from a prompt, or edit one to three local raster images. Uses the xAI Grok subscription OAuth login, saves the result under Tau's external image store unless an explicit path is provided, and returns the image for inspection.",
+			promptSnippet: "Generate or edit raster images with Grok Imagine",
 			promptGuidelines: [
 				"Use image_gen when the user asks for a generated raster image or an AI edit of local raster images.",
 				"Omit referenced_image_paths when image_gen should create a new image.",
-				"Pass one to five local paths in referenced_image_paths when image_gen should edit or compose existing images.",
+				"Pass one to three local paths in referenced_image_paths when image_gen should edit or compose existing images.",
 				"Omit path for temporary external storage. Pass path only when the user wants the generated image saved in their repository or another explicit location.",
 			],
 			parameters: imageGenSchema,
@@ -66,18 +56,22 @@ export default function imageGenExtension(pi: ExtensionAPI): void {
 				if (!prompt) throw new Error("Image prompt cannot be empty");
 				const requestedPath = params.path?.startsWith("@") ? params.path.slice(1) : params.path;
 				if (requestedPath !== undefined && !requestedPath.trim()) throw new Error("Image path cannot be empty");
-				const absolutePath = requestedPath
+				const requestedAbsolutePath = requestedPath
 					? isAbsolute(requestedPath)
 						? requestedPath
 						: resolve(ctx.cwd, requestedPath)
-					: join(homedir(), ".local", "share", "tau-agent", "images", `image-${randomUUID()}.png`);
-				if (!absolutePath.toLowerCase().endsWith(".png")) throw new Error("Image path must end in .png");
+					: undefined;
+				if (
+					requestedAbsolutePath &&
+					![".jpg", ".jpeg", ".png", ".webp"].includes(extname(requestedAbsolutePath).toLowerCase())
+				) {
+					throw new Error("Image path must end in .jpg, .jpeg, .png, or .webp");
+				}
 
-				const token = await ctx.modelRegistry.getApiKeyForProvider("openai-codex");
+				const token = await ctx.modelRegistry.getApiKeyForProvider(XAI_PROVIDER);
 				if (!token) {
-					throw new Error("OpenAI Codex OAuth is unavailable. Run /login and select OpenAI Codex.");
+					throw new Error("xAI OAuth is unavailable. Run /login and select xAI (Grok subscription OAuth).");
 				}
-				const auth = resolveCodexAuth(token);
 				const images: EditImage[] = [];
 				for (const path of params.referenced_image_paths ?? []) {
 					const rawPath = path.startsWith("@") ? path.slice(1) : path;
@@ -101,22 +95,37 @@ export default function imageGenExtension(pi: ExtensionAPI): void {
 							type: "text",
 							text:
 								operation === "generate"
-									? `Generating image with ${MODEL}...`
-									: `Editing image with ${MODEL}...`,
+									? `Generating image with ${XAI_IMAGE_MODEL}...`
+									: `Editing image with ${XAI_IMAGE_MODEL}...`,
 						},
 					],
 					details: undefined,
 				});
 				const generated =
 					operation === "generate"
-						? await generateImage(prompt, auth, signal)
-						: await editImage(prompt, images, auth, signal);
+						? await generateImage(prompt, token, signal)
+						: await editImage(prompt, images, token, signal);
 				signal?.throwIfAborted();
+				const generatedExtension = outputExtension(generated);
+				if (requestedAbsolutePath) {
+					const requestedExtension = extname(requestedAbsolutePath).toLowerCase();
+					const matches =
+						requestedExtension === generatedExtension ||
+						(generatedExtension === ".jpg" && requestedExtension === ".jpeg");
+					if (!matches)
+						throw new Error(`xAI returned ${generated.mimeType}; destination must end in ${generatedExtension}`);
+				}
+				const absolutePath =
+					requestedAbsolutePath ??
+					join(homedir(), ".local", "share", "tau-agent", "images", `image-${randomUUID()}${generatedExtension}`);
 
 				const outputDirectory = dirname(absolutePath);
 				await withFileMutationQueue(absolutePath, async () => {
 					await mkdir(outputDirectory, { recursive: true });
-					const temporaryPath = join(outputDirectory, `.${basename(absolutePath)}.${randomUUID()}.tmp.png`);
+					const temporaryPath = join(
+						outputDirectory,
+						`.${basename(absolutePath)}.${randomUUID()}.tmp${generatedExtension}`,
+					);
 					try {
 						await writeFile(temporaryPath, generated.bytes, { flag: "wx" });
 						signal?.throwIfAborted();
@@ -127,7 +136,7 @@ export default function imageGenExtension(pi: ExtensionAPI): void {
 				});
 
 				const verb = operation === "generate" ? "Generated" : "Edited";
-				const details: ImageGenDetails = { path: absolutePath, model: MODEL, operation };
+				const details: ImageGenDetails = { path: absolutePath, model: XAI_IMAGE_MODEL, operation };
 				if (generated.bytes.length > MAX_INLINE_BYTES) {
 					return {
 						content: [

package/extensions/subagent/README.md

@@ -7,7 +7,6 @@ Agent definitions can override the parent model and thinking level. If an overri
 Tau includes three built-in agents:
 
 - `scout` explores local files and code with `read`, `grep`, `find`, and `ls`.
-- `context-maintenance` reconciles reusable repository context entries and requests approval before updates.
 - `web-research` researches web and code sources with `websearch`, `codesearch`, and `webfetch`.
 
 Ask Tau to delegate a task, or let it call `subagent` with an agent name and task. Children use the parent's current working directory and inherit its model and thinking level unless their definition overrides either value. They do not receive the parent conversation. Tau loads only the extensions that own a child's declared tools, so unrelated extension hooks do not run in child sessions. When a child must inspect another repository, put its exact absolute path in the delegated task.

package/extensions/subagent/agents.ts

@@ -126,10 +126,6 @@ async function loadScope(
 		const reason = error instanceof Error ? error.message : "directory unavailable";
 		return new Map([
 			["scout", [{ path: directory, name: "scout", reason: `packaged agents unavailable: ${reason}` }]],
-			[
-				"context-maintenance",
-				[{ path: directory, name: "context-maintenance", reason: `packaged agents unavailable: ${reason}` }],
-			],
 			[
 				"web-research",
 				[{ path: directory, name: "web-research", reason: `packaged agents unavailable: ${reason}` }],

package/extensions/tau-help/help.md

@@ -28,11 +28,11 @@ Adds `/commit` for semantic commit grouping, review, and committing selected rep
 
 ## context
 
-Adds `/context` to select reusable repository work scopes from `.pi/contexts`, and `/context-manage <idea>` to run interactive, approval-based catalog maintenance. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
+Adds `/context` to select reusable repository work scopes from `.pi/contexts`, and `/context-sync` to reconcile affected scopes from current Git changes. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
 
 ## explore
 
-Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `find`, `grep`, and `read`. They produce smaller model payloads and readable tool rows. `read` includes focused line ranges; `grep`, `find`, and `ls` keep discovery output compact so the agent spends fewer tokens rereading directory and search results.
+Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `find`, `grep`, and `read`. They produce smaller model payloads and readable tool rows. Repeated `read` calls return unchanged markers or useful diffs when branch history proves the agent already saw the base content. A failed patch unlocks one normal reread of the affected path. `/read-stats` shows estimated token and cost savings for the current chat and whole session.
 
 ## footer
 
@@ -46,6 +46,10 @@ Adds `/ideas` to log rough ideas or open the ideas browser.
 
 Gives the agent an image-generation tool using the configured image service. Generated images are saved for inspection.
 
+## xai
+
+Adds Grok 4.5 and Grok Imagine through an xAI Grok subscription OAuth login. Run `/login` and select xAI before use.
+
 ## manage-sessions
 
 Adds `/manage-sessions` to browse saved sessions and `/sweep` to archive or delete the current session after starting a new one.
@@ -84,7 +88,7 @@ Adds `Alt+S` to stash the current prompt draft and `/pop` to browse stashed draf
 
 ## subagent
 
-Gives Tau a subagent delegation tool for isolated, focused work. You can also create your own subagents in the supported subagent directories. Ask Tau how to do it and have it consult the extension’s own documentation; the built-in `scout`, `context-maintenance`, and `web-research` subagents show the pattern. Each subagent can register its own model and the tools it is allowed to use.
+Gives Tau a subagent delegation tool for isolated, focused work. You can also create your own subagents in the supported subagent directories. Ask Tau how to do it and have it consult the extension’s own documentation; the built-in `scout` and `web-research` subagents show the pattern. Each subagent can register its own model and the tools it is allowed to use.
 
 ## tau-help
 

package/extensions/xai/README.md

@@ -0,0 +1,7 @@
+# xAI OAuth
+
+Adds Grok 4.5 using an xAI Grok subscription login. Run `/login`, select **xAI (Grok subscription OAuth)**, then authorize xAI in the browser. An existing official Grok CLI login can also be reused.
+
+The same login powers Tau's `image_gen` tool through Grok Imagine. No xAI API key is used.
+
+This integration uses xAI's undocumented subscription OAuth access. xAI may change its availability, entitlement rules, or protocol without notice.

package/extensions/xai/auth.ts

@@ -0,0 +1,40 @@
+import type { OAuthCredentials } from "@earendil-works/pi-ai";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { XAI_OAUTH_CLIENT_ID, XAI_OAUTH_ISSUER } from "./constants.ts";
+
+function expiry(value: unknown): number | undefined {
+	if (typeof value === "number" && Number.isInteger(value) && value >= 1_000_000_000_000) return value;
+	if (typeof value !== "string") return undefined;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function parseGrokCredentials(value: unknown): OAuthCredentials | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const entry = (value as Record<string, unknown>)[`${XAI_OAUTH_ISSUER}::${XAI_OAUTH_CLIENT_ID}`];
+	if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return undefined;
+	const record = entry as Record<string, unknown>;
+	const expires = expiry(record.expires_at);
+	if (
+		typeof record.key !== "string" ||
+		!record.key ||
+		typeof record.refresh_token !== "string" ||
+		!record.refresh_token ||
+		record.oidc_issuer !== XAI_OAUTH_ISSUER ||
+		record.oidc_client_id !== XAI_OAUTH_CLIENT_ID ||
+		expires === undefined
+	) {
+		return undefined;
+	}
+	return { access: record.key, refresh: record.refresh_token, expires };
+}
+
+export async function readGrokCredentials(): Promise<OAuthCredentials | undefined> {
+	try {
+		return parseGrokCredentials(JSON.parse(await readFile(join(homedir(), ".grok", "auth.json"), "utf8")));
+	} catch {
+		return undefined;
+	}
+}

package/extensions/xai/constants.ts

@@ -0,0 +1,11 @@
+export const XAI_PROVIDER = "xai-oauth";
+export const XAI_CHAT_MODEL = "grok-4.5";
+export const XAI_IMAGE_MODEL = "grok-imagine-image-quality";
+export const XAI_API_BASE_URL = "https://api.x.ai/v1";
+
+export const XAI_OAUTH_ISSUER = "https://auth.x.ai";
+export const XAI_OAUTH_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+export const XAI_OAUTH_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+export const XAI_OAUTH_CALLBACK_HOST = "127.0.0.1";
+export const XAI_OAUTH_CALLBACK_PORT = 56121;
+export const XAI_OAUTH_CALLBACK_PATH = "/callback";

package/extensions/xai/index.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { XAI_API_BASE_URL, XAI_CHAT_MODEL, XAI_PROVIDER } from "./constants.ts";
+import { xaiOAuth } from "./oauth.ts";
+import { rewriteXaiPayload } from "./payload.ts";
+
+export default function xaiExtension(pi: ExtensionAPI): void {
+	pi.registerProvider(XAI_PROVIDER, {
+		name: "xAI (Grok subscription OAuth)",
+		baseUrl: XAI_API_BASE_URL,
+		api: "openai-responses",
+		authHeader: true,
+		oauth: xaiOAuth,
+		models: [
+			{
+				id: XAI_CHAT_MODEL,
+				name: "Grok 4.5",
+				reasoning: true,
+				input: ["text", "image"],
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 500_000,
+				maxTokens: 131_072,
+				thinkingLevelMap: {
+					off: null,
+					minimal: "low",
+					low: "low",
+					medium: "medium",
+					high: "high",
+					xhigh: null,
+					max: null,
+				},
+			},
+		],
+	});
+	pi.on("before_provider_request", (event, ctx) => {
+		if (ctx.model?.provider !== XAI_PROVIDER) return;
+		return rewriteXaiPayload(event.payload);
+	});
+}

package/extensions/xai/oauth.ts

@@ -0,0 +1,342 @@
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import { readGrokCredentials } from "./auth.ts";
+import {
+	XAI_OAUTH_CALLBACK_HOST,
+	XAI_OAUTH_CALLBACK_PATH,
+	XAI_OAUTH_CALLBACK_PORT,
+	XAI_OAUTH_CLIENT_ID,
+	XAI_OAUTH_ISSUER,
+	XAI_OAUTH_SCOPE,
+} from "./constants.ts";
+
+const DISCOVERY_URL = `${XAI_OAUTH_ISSUER}/.well-known/openid-configuration`;
+const REQUEST_TIMEOUT_MS = 30_000;
+const LOGIN_TIMEOUT_MS = 180_000;
+const REFRESH_SKEW_MS = 120_000;
+
+interface Discovery {
+	authorization_endpoint: string;
+	token_endpoint: string;
+}
+
+interface TokenPayload {
+	access_token?: unknown;
+	refresh_token?: unknown;
+	id_token?: unknown;
+	expires_in?: unknown;
+	token_type?: unknown;
+}
+
+interface HttpResponse {
+	ok: boolean;
+	status: number;
+	body: { cancel(): Promise<void> } | null;
+	json(): Promise<unknown>;
+}
+
+interface CallbackResult {
+	code?: string;
+	error?: string;
+	errorDescription?: string;
+}
+
+function validatedEndpoint(value: unknown, field: string): string {
+	if (typeof value !== "string") throw new Error(`xAI OAuth discovery omitted ${field}`);
+	const url = new URL(value);
+	const host = url.hostname.toLowerCase();
+	if (url.protocol !== "https:" || (host !== "x.ai" && !host.endsWith(".x.ai"))) {
+		throw new Error(`xAI OAuth discovery returned an unexpected ${field}`);
+	}
+	return url.toString();
+}
+
+function requestSignal(parent?: AbortSignal): AbortSignal {
+	const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+	return parent ? AbortSignal.any([parent, timeout]) : timeout;
+}
+
+async function discover(signal?: AbortSignal): Promise<Discovery> {
+	const response = (await fetch(DISCOVERY_URL, {
+		headers: { Accept: "application/json" },
+		signal: requestSignal(signal),
+	})) as HttpResponse;
+	if (!response.ok) throw new Error(`xAI OAuth discovery failed with status ${response.status}`);
+	const value: unknown = await response.json();
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new Error("xAI OAuth discovery returned invalid JSON");
+	}
+	const record = value as Record<string, unknown>;
+	return {
+		authorization_endpoint: validatedEndpoint(record.authorization_endpoint, "authorization_endpoint"),
+		token_endpoint: validatedEndpoint(record.token_endpoint, "token_endpoint"),
+	};
+}
+
+async function tokenRequest(endpoint: string, body: URLSearchParams, signal?: AbortSignal): Promise<TokenPayload> {
+	const response = (await fetch(validatedEndpoint(endpoint, "token_endpoint"), {
+		method: "POST",
+		headers: { Accept: "application/json", "Content-Type": "application/x-www-form-urlencoded" },
+		body,
+		signal: requestSignal(signal),
+	})) as HttpResponse;
+	if (!response.ok) {
+		await response.body?.cancel().catch(() => undefined);
+		throw new Error(`xAI OAuth token request failed with status ${response.status}`);
+	}
+	return (await response.json()) as TokenPayload;
+}
+
+function jwtClaims(token: string): Record<string, unknown> {
+	const segments = token.split(".");
+	if (segments.length !== 3 || !segments[1]) throw new Error("xAI OAuth returned an invalid ID token");
+	try {
+		const value: unknown = JSON.parse(Buffer.from(segments[1], "base64url").toString("utf8"));
+		if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error();
+		return value as Record<string, unknown>;
+	} catch {
+		throw new Error("xAI OAuth returned an invalid ID token");
+	}
+}
+
+function credentials(payload: TokenPayload, endpoint: string, fallbackRefresh = "", nonce?: string): OAuthCredentials {
+	if (typeof payload.access_token !== "string" || !payload.access_token) {
+		throw new Error("xAI OAuth token response omitted the access token");
+	}
+	const refresh =
+		typeof payload.refresh_token === "string" && payload.refresh_token ? payload.refresh_token : fallbackRefresh;
+	if (!refresh) throw new Error("xAI OAuth token response omitted the refresh token");
+	if (nonce !== undefined) {
+		if (typeof payload.id_token !== "string" || !payload.id_token)
+			throw new Error("xAI OAuth token response omitted the ID token");
+		const claims = jwtClaims(payload.id_token);
+		const audience = claims.aud;
+		const validAudience =
+			audience === XAI_OAUTH_CLIENT_ID || (Array.isArray(audience) && audience.includes(XAI_OAUTH_CLIENT_ID));
+		if (claims.iss !== XAI_OAUTH_ISSUER || !validAudience || claims.nonce !== nonce) {
+			throw new Error("xAI OAuth ID token validation failed");
+		}
+		if (typeof claims.exp !== "number" || claims.exp * 1000 <= Date.now()) {
+			throw new Error("xAI OAuth returned an expired ID token");
+		}
+	}
+	const expiresIn = typeof payload.expires_in === "number" && payload.expires_in > 0 ? payload.expires_in : 3600;
+	return {
+		access: payload.access_token,
+		refresh,
+		expires: Date.now() + expiresIn * 1000 - REFRESH_SKEW_MS,
+		tokenEndpoint: endpoint,
+	};
+}
+
+async function closeServer(server: Server): Promise<void> {
+	if (!server.listening) return;
+	await new Promise<void>((resolve) => server.close(() => resolve()));
+}
+
+async function callbackServer(expectedState: string): Promise<{
+	redirectUri: string;
+	wait(signal?: AbortSignal): Promise<CallbackResult>;
+	acceptManual(input: string): string | undefined;
+	close(): Promise<void>;
+}> {
+	let settle: ((result: CallbackResult) => void) | undefined;
+	let reject: ((error: Error) => void) | undefined;
+	let settled = false;
+	const result = new Promise<CallbackResult>((resolve, rejectResult) => {
+		settle = resolve;
+		reject = rejectResult;
+	});
+	const accept = (value: CallbackResult) => {
+		if (settled) return;
+		settled = true;
+		settle?.(value);
+	};
+	const parse = (params: URLSearchParams): CallbackResult | undefined => {
+		if (params.get("state") !== expectedState) return undefined;
+		const code = params.get("code") || undefined;
+		const error = params.get("error") || undefined;
+		if (!code && !error) return undefined;
+		return { code, error, errorDescription: params.get("error_description") || undefined };
+	};
+	const server = createServer((request, response) => {
+		const origin = request.headers.origin;
+		if (origin === "https://accounts.x.ai" || origin === "https://auth.x.ai") {
+			response.setHeader("Access-Control-Allow-Origin", origin);
+			response.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+			response.setHeader("Access-Control-Allow-Headers", "Content-Type");
+			response.setHeader("Access-Control-Allow-Private-Network", "true");
+			response.setHeader("Vary", "Origin");
+		}
+		if (request.method === "OPTIONS") {
+			response.writeHead(204).end();
+			return;
+		}
+		const url = new URL(request.url ?? "/", `http://${XAI_OAUTH_CALLBACK_HOST}`);
+		if (request.method !== "GET" || url.pathname !== XAI_OAUTH_CALLBACK_PATH) {
+			response.writeHead(404).end("Not found");
+			return;
+		}
+		const parsed = parse(url.searchParams);
+		if (!parsed) {
+			response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" }).end("Invalid OAuth callback");
+			return;
+		}
+		response
+			.writeHead(parsed.error ? 400 : 200, { "Content-Type": "text/html; charset=utf-8" })
+			.end("<html><body><h1>xAI authorization received.</h1>You can close this tab.</body></html>", () =>
+				accept(parsed),
+			);
+	});
+	const listen = (port: number) =>
+		new Promise<number>((resolve, rejectListen) => {
+			server.once("error", rejectListen);
+			server.listen(port, XAI_OAUTH_CALLBACK_HOST, () => {
+				server.removeListener("error", rejectListen);
+				const address = server.address();
+				if (!address || typeof address === "string") rejectListen(new Error("Could not determine callback port"));
+				else resolve(address.port);
+			});
+		});
+	let port: number;
+	try {
+		port = await listen(XAI_OAUTH_CALLBACK_PORT);
+	} catch {
+		port = await listen(0);
+	}
+	return {
+		redirectUri: `http://${XAI_OAUTH_CALLBACK_HOST}:${port}${XAI_OAUTH_CALLBACK_PATH}`,
+		acceptManual(input) {
+			try {
+				const value = input.trim();
+				const url = value.startsWith("http")
+					? new URL(value)
+					: new URL(`http://${XAI_OAUTH_CALLBACK_HOST}${XAI_OAUTH_CALLBACK_PATH}?${value.replace(/^\?/, "")}`);
+				if (url.pathname !== XAI_OAUTH_CALLBACK_PATH) return "Callback URL path was not recognized";
+				const parsed = parse(url.searchParams);
+				if (!parsed) return "Callback state did not match";
+				accept(parsed);
+				return undefined;
+			} catch {
+				return "Callback URL was invalid";
+			}
+		},
+		async wait(signal) {
+			const timeout = setTimeout(() => {
+				if (!settled) {
+					settled = true;
+					reject?.(new Error("Timed out waiting for xAI OAuth callback"));
+				}
+			}, LOGIN_TIMEOUT_MS);
+			const onAbort = () => {
+				if (!settled) {
+					settled = true;
+					reject?.(new Error("xAI OAuth login was cancelled"));
+				}
+			};
+			signal?.addEventListener("abort", onAbort, { once: true });
+			try {
+				return await result;
+			} finally {
+				clearTimeout(timeout);
+				signal?.removeEventListener("abort", onAbort);
+				await closeServer(server);
+			}
+		},
+		close: () => closeServer(server),
+	};
+}
+
+async function refreshXaiCredentials(value: OAuthCredentials): Promise<OAuthCredentials> {
+	if (!value.refresh) throw new Error("xAI OAuth credential cannot be refreshed; run /login again");
+	const endpoint =
+		typeof value.tokenEndpoint === "string" && value.tokenEndpoint
+			? validatedEndpoint(value.tokenEndpoint, "token_endpoint")
+			: (await discover()).token_endpoint;
+	const payload = await tokenRequest(
+		endpoint,
+		new URLSearchParams({
+			grant_type: "refresh_token",
+			client_id: XAI_OAUTH_CLIENT_ID,
+			refresh_token: value.refresh,
+		}),
+	);
+	return credentials(payload, endpoint, value.refresh);
+}
+
+export const xaiOAuth = {
+	name: "xAI (Grok subscription)",
+	usesCallbackServer: true,
+	async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+		const existing = await readGrokCredentials();
+		if (existing) {
+			const method = await callbacks.onSelect({
+				message: "Select xAI login method:",
+				options: [
+					{ id: "browser", label: "Browser login" },
+					{ id: "existing", label: "Use existing Grok CLI login" },
+				],
+			});
+			if (!method) throw new Error("Login cancelled");
+			if (method === "existing") {
+				if (existing.expires > Date.now()) return existing;
+				try {
+					return await refreshXaiCredentials(existing);
+				} catch {
+					callbacks.onProgress?.("The existing Grok CLI login could not be refreshed. Starting browser login.");
+				}
+			}
+		}
+		const discovery = await discover(callbacks.signal);
+		const verifier = randomBytes(32).toString("base64url");
+		const challenge = createHash("sha256").update(verifier).digest("base64url");
+		const state = randomBytes(24).toString("base64url");
+		const nonce = randomBytes(24).toString("base64url");
+		const callback = await callbackServer(state);
+		try {
+			const url = new URL(discovery.authorization_endpoint);
+			url.search = new URLSearchParams({
+				response_type: "code",
+				client_id: XAI_OAUTH_CLIENT_ID,
+				redirect_uri: callback.redirectUri,
+				scope: XAI_OAUTH_SCOPE,
+				code_challenge: challenge,
+				code_challenge_method: "S256",
+				state,
+				nonce,
+			}).toString();
+			callbacks.onAuth({ url: url.toString(), instructions: "Authorize xAI in your browser, then return to Tau." });
+			if (callbacks.onManualCodeInput) {
+				void callbacks
+					.onManualCodeInput()
+					.then((input) => {
+						const error = callback.acceptManual(input);
+						if (error) callbacks.onProgress?.(`Ignored pasted callback: ${error}`);
+					})
+					.catch(() => undefined);
+			}
+			const result = await callback.wait(callbacks.signal);
+			if (result.error) throw new Error(`xAI authorization failed: ${result.errorDescription ?? result.error}`);
+			if (!result.code) throw new Error("xAI authorization did not return a code");
+			const payload = await tokenRequest(
+				discovery.token_endpoint,
+				new URLSearchParams({
+					grant_type: "authorization_code",
+					client_id: XAI_OAUTH_CLIENT_ID,
+					code: result.code,
+					redirect_uri: callback.redirectUri,
+					code_verifier: verifier,
+				}),
+				callbacks.signal,
+			);
+			return credentials(payload, discovery.token_endpoint, "", nonce);
+		} finally {
+			await callback.close();
+		}
+	},
+	refreshToken: refreshXaiCredentials,
+	getApiKey(value: OAuthCredentials): string {
+		return value.access;
+	},
+};