dsh-coding-subscription-oauth 0.5.0

package/scripts/smoke-deployed-routes.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+import { randomUUID } from "node:crypto";
+
+const base = new URL(process.env.DSH_WEB_URL ?? "http://127.0.0.1:3080");
+const origin = base.origin;
+const timeoutMs = Number.parseInt(process.env.DSH_SMOKE_TIMEOUT_MS ?? "180000", 10);
+const restoreProvider = process.env.DSH_RESTORE_PROVIDER;
+const restoreModel = process.env.DSH_RESTORE_MODEL;
+if (restoreProvider === undefined || restoreModel === undefined) {
+	throw new Error(
+		"Set DSH_RESTORE_PROVIDER and DSH_RESTORE_MODEL before running; smoke selection updates the saved default temporarily",
+	);
+}
+const restoreSelection = {
+	provider: restoreProvider,
+	model: restoreModel,
+	...(process.env.DSH_RESTORE_REASONING === undefined ? {} : { reasoningEffort: process.env.DSH_RESTORE_REASONING }),
+};
+const cases = [
+	{
+		route: "codex-oauth",
+		model: process.env.DSH_CODEX_SMOKE_MODEL ?? "gpt-5.6-sol",
+		marker: "DSH_CODEX_OAUTH_SMOKE_OK",
+	},
+	{ route: "kimi-code-oauth", model: process.env.DSH_KIMI_SMOKE_MODEL ?? "k3", marker: "DSH_KIMI_OAUTH_SMOKE_OK" },
+];
+
+async function rpc(method, payload) {
+	const rpcId = randomUUID();
+	const response = await fetch(new URL(`/api/${method}`, base), {
+		method: "POST",
+		headers: { accept: "application/json", "content-type": "application/json", origin },
+		body: JSON.stringify({ type: "client-request", rpcId, method, payload }),
+		signal: AbortSignal.timeout(30_000),
+	});
+	const envelope = await response.json().catch(() => undefined);
+	if (!response.ok) throw new Error(`${method}: HTTP ${response.status}`);
+	if (envelope?.rpcId !== rpcId || envelope?.result?.ok !== true) {
+		throw new Error(`${method}: ${envelope?.result?.error?.message ?? "invalid response"}`);
+	}
+	return envelope.result.value;
+}
+
+async function waitForIdle(sessionId) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const { items } = await rpc("session.list", {});
+		const session = items.find((item) => item.sessionId === sessionId);
+		if (session === undefined) throw new Error(`session ${sessionId} disappeared`);
+		if (!session.blank && !session.running) return;
+		await new Promise((resolve) => setTimeout(resolve, 1_000));
+	}
+	throw new Error(`session ${sessionId} did not finish within ${timeoutMs}ms`);
+}
+
+function contentBlocks(value, output = []) {
+	if (Array.isArray(value)) {
+		for (const item of value) contentBlocks(item, output);
+	} else if (value !== null && typeof value === "object") {
+		if (typeof value.type === "string" && ["tool-call", "tool-result"].includes(value.type)) output.push(value);
+		for (const child of Object.values(value)) contentBlocks(child, output);
+	}
+	return output;
+}
+
+async function runSmoke(testCase) {
+	const created = await rpc("session.create", { cwd: process.cwd() });
+	const sessionId = created.sessionId;
+	let selected = false;
+	let failure;
+	try {
+		await rpc("session.selectModel", {
+			sessionId,
+			provider: testCase.route,
+			model: testCase.model,
+			reasoningEffort: "low",
+		});
+		selected = true;
+		await rpc("session.prompt", {
+			sessionId,
+			mode: "queue",
+			clientTimeZone: "UTC",
+			content: [
+				{
+					type: "text",
+					text: `Automated OAuth smoke test. You MUST call the glob tool exactly once with pattern "package.json" in the current workspace. After receiving the tool result, reply with exactly ${testCase.marker} and no other text.`,
+				},
+			],
+		});
+		await waitForIdle(sessionId);
+		const history = await rpc("session.history", { sessionId, maxMessages: 200 });
+		const serialized = JSON.stringify(history.events);
+		const blocks = contentBlocks(history.events);
+		const toolCalls = blocks.filter((block) => block.type === "tool-call").length;
+		const toolResults = blocks.filter((block) => block.type === "tool-result").length;
+		const eventTypes = [...new Set(history.events.map((entry) => entry.event.type))];
+		const turnErrors = eventTypes.filter((type) => type.includes("error"));
+		if (!serialized.includes(testCase.marker)) throw new Error(`${testCase.route}: response marker missing`);
+		if (toolCalls === 0 || toolResults === 0) throw new Error(`${testCase.route}: tool-call round trip missing`);
+		if (turnErrors.length > 0) throw new Error(`${testCase.route}: error events: ${turnErrors.join(", ")}`);
+
+		const secondMarker = `${testCase.marker}_TURN2`;
+		await rpc("session.prompt", {
+			sessionId,
+			mode: "queue",
+			clientTimeZone: "UTC",
+			content: [
+				{ type: "text", text: `Second-turn replay test. Reply with exactly ${secondMarker} and no other text.` },
+			],
+		});
+		await waitForIdle(sessionId);
+		const secondHistory = await rpc("session.history", { sessionId, maxMessages: 200 });
+		const secondSerialized = JSON.stringify(secondHistory.events);
+		const secondEventTypes = [...new Set(secondHistory.events.map((entry) => entry.event.type))];
+		const secondTurnErrors = secondEventTypes.filter((type) => type.includes("error"));
+		if (!secondSerialized.includes(secondMarker))
+			throw new Error(`${testCase.route}: second-turn response marker missing`);
+		if (secondTurnErrors.length > 0)
+			throw new Error(`${testCase.route}: second-turn error events: ${secondTurnErrors.join(", ")}`);
+		console.log(`${testCase.route}/${testCase.model}: twoTurns=yes toolCalls=${toolCalls} toolResults=${toolResults}`);
+	} catch (error) {
+		failure = error;
+	} finally {
+		if (selected) {
+			try {
+				await rpc("session.selectModel", { sessionId, ...restoreSelection });
+			} catch (error) {
+				failure ??= new Error(
+					`${testCase.route}: failed to restore default model: ${error instanceof Error ? error.message : String(error)}`,
+				);
+			}
+		}
+		try {
+			await rpc("workspace.archiveSession", { sessionId });
+		} catch (error) {
+			failure ??= new Error(
+				`${testCase.route}: failed to archive smoke session: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+	if (failure !== undefined) throw failure;
+}
+
+for (const testCase of cases) await runSmoke(testCase);
+console.log("Deployed Codex/Kimi OAuth inference and tool-call smoke passed.");

package/scripts/verify-deployed-catalog.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { randomUUID } from "node:crypto";
+
+const base = new URL(process.env.DSH_WEB_URL ?? "http://127.0.0.1:3080");
+const origin = base.origin;
+
+async function jsonFetch(path, init = {}) {
+	const response = await fetch(new URL(path, base), {
+		...init,
+		headers: {
+			accept: "application/json",
+			origin,
+			...init.headers,
+		},
+	});
+	const value = await response.json().catch(() => undefined);
+	if (!response.ok) throw new Error(`${path}: HTTP ${response.status}`);
+	return value;
+}
+
+async function rpc(method, payload = {}) {
+	const rpcId = randomUUID();
+	const envelope = await jsonFetch(`/api/${method}`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ type: "client-request", rpcId, method, payload }),
+	});
+	if (envelope?.rpcId !== rpcId || envelope?.result?.ok !== true) {
+		throw new Error(`${method} failed: ${JSON.stringify(envelope?.result?.error ?? envelope)}`);
+	}
+	return envelope.result.value;
+}
+
+const status = await jsonFetch("/plugins/dsh-grok-build/oauth/status");
+const catalog = await rpc("llm.models");
+const registered = await rpc("llm.providers");
+const groups = new Map(catalog.groups.map((group) => [group.id, group]));
+const routes = [
+	["grok", "grok-build"],
+	["codex", "codex-oauth"],
+	["kimi", "kimi-code-oauth"],
+	["claude", "claude-code-oauth"],
+];
+const failures = [];
+const report = [];
+for (const [slug, route] of routes) {
+	const authenticated = status?.providers?.[slug]?.status === "signed-in";
+	const group = groups.get(route);
+	if (authenticated && group === undefined) failures.push(`${route}: authenticated but absent from model catalog`);
+	if (!authenticated && group !== undefined)
+		failures.push(`${route}: unauthenticated but still advertises ${group.models.length} model(s)`);
+	if (group !== undefined && !/\(OAuth\)$/u.test(group.name))
+		failures.push(`${route}: provider name lacks (OAuth): ${group.name}`);
+	report.push(
+		`${route}: ${authenticated ? "authenticated" : "unauthenticated"} → ${group === undefined ? "hidden" : `${group.models.length} model(s), ${group.name}`}`,
+	);
+}
+
+const providerIds = new Set(registered.providers.map((provider) => provider.provider));
+const preservedRoutes = ["openai", "xai", "kimi-coding"];
+for (const route of preservedRoutes) {
+	if (!providerIds.has(route)) failures.push(`${route}: legacy API-key route is no longer registered`);
+}
+report.push(`preserved API-key routes: ${preservedRoutes.filter((route) => providerIds.has(route)).join(", ")}`);
+
+const agyExpectation = process.env.DSH_EXPECT_AGY_AUTH ?? "signed-out";
+if (!["signed-out", "signed-in", "auto"].includes(agyExpectation)) {
+	throw new Error("DSH_EXPECT_AGY_AUTH must be signed-out, signed-in, or auto");
+}
+const agy = groups.get("agy");
+if (agyExpectation === "signed-out" && agy !== undefined)
+	failures.push(`agy: expected signed-out but advertises ${agy.models.length} model(s)`);
+if (agyExpectation === "signed-in" && agy === undefined)
+	failures.push("agy: expected signed-in but absent from model catalog");
+if (agy !== undefined && agy.name !== "Google Antigravity (OAuth)")
+	failures.push(`agy: provider name lacks OAuth label: ${agy.name}`);
+report.push(`agy: ${agy === undefined ? "hidden" : `${agy.models.length} model(s), ${agy.name}`}`);
+
+console.log(report.join("\n"));
+if (failures.length > 0) {
+	console.error("\nDeployment verification failed:");
+	for (const failure of failures) console.error(`- ${failure}`);
+	process.exitCode = 1;
+} else {
+	console.log("\nOAuth model catalog verification passed.");
+}

package/src/adapter.ts

@@ -0,0 +1,282 @@
+/** Coding-subscription adapter assembled from public dsh-llm-pi-ai extension points. */
+
+import type { AttachmentStore } from "@deepseek-ai/dsh-attachment";
+import type { RetryPolicyConfig } from "@deepseek-ai/dsh-llm";
+import { type LlmAdapter, LlmError, resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
+import type { ResolvedPiAiProviderProfile } from "@deepseek-ai/dsh-llm-pi-ai";
+import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
+import type { AliasLlmRoutePolicy } from "./alias-adapter.ts";
+import { AliasLlmAdapter } from "./alias-adapter.ts";
+import { preferredGrokBuildModelFrom } from "./catalog.ts";
+import { withCodexFastRouting } from "./codex-model-capabilities.ts";
+import {
+	CLAUDE_CODE_OAUTH_ROUTE,
+	CLAUDE_PI_PROVIDER,
+	CODEX_OAUTH_FAST_ROUTE,
+	CODEX_OAUTH_ROUTE,
+	CODEX_PI_PROVIDER,
+	DEFAULT_GROK_BUILD_MODEL,
+	GROK_BUILD_ROUTE,
+	GROK_BUILD_STREAM_IDLE_TIMEOUT_MS,
+	KIMI_CODE_OAUTH_ROUTE,
+	KIMI_PI_PROVIDER,
+	XAI_PI_PROVIDER,
+} from "./ids.ts";
+import type { OAuthProviderSession } from "./oauth-session.ts";
+import { grokBuildBaselineModels, grokBuildFingerprintHeaders } from "./provider.ts";
+import { safeMessage } from "./redact.ts";
+import type { GrokBuildSession } from "./session.ts";
+
+/** Prefer grok-4.6 when the current (live or baseline) list has it. */
+export function preferredGrokBuildModel(models: readonly { id: string }[] = grokBuildBaselineModels()): string {
+	return preferredGrokBuildModelFrom(models.length === 0 ? [{ id: DEFAULT_GROK_BUILD_MODEL }] : models);
+}
+
+function missingCredential(name: string): never {
+	throw new LlmError(
+		`${name} is not signed in. Open Settings → Coding OAuth and sign in with your subscription.`,
+		"MISSING_CREDENTIAL",
+	);
+}
+
+/**
+ * Minimum remaining validity demanded of an exported OAuth access token.
+ * pi-ai 0.84+ already refreshes five minutes before the stored expiry; this
+ * explicit floor documents the plugin contract and hard-fails a refresh that
+ * returns an even-shorter-lived token instead of handing it to a request.
+ */
+const MIN_OAUTH_VALIDITY_MS = 60_000;
+
+/**
+ * Provider retry policy for the coding-subscription routes. The harness
+ * default retryable set (EMPTY_RESPONSE/RATE_LIMIT/SERVER/TIMEOUT/TRANSPORT)
+ * deliberately excludes AUTH, so an upstream 401 — e.g. an access token the
+ * server revoked before its local expiry — used to kill the turn outright.
+ * AUTH is added here because {@link AliasLlmAdapter} invalidates the stored
+ * credential on every AUTH finish, so the retried step refreshes first and
+ * does not repeat the same rejected token. Quota exhaustion stays outside the
+ * set: retrying a billing-limit 403 cannot succeed and only delays the real
+ * message. Genuine credential death is converted to MISSING_CREDENTIAL (not
+ * retryable) by the resolver below, so it cannot loop either.
+ */
+const CODING_OAUTH_RETRY_POLICY = {
+	mode: "normal" as const,
+	maxRetries: 2,
+	retryableCodes: ["EMPTY_RESPONSE", "RATE_LIMIT", "SERVER", "TIMEOUT", "TRANSPORT", "AUTH"],
+	backoff: { initialDelayMs: 500, maxDelayMs: 10_000, jitterRatio: 0.1 },
+};
+
+function profile(
+	provider: string,
+	displayName: string,
+	piProvider: ResolvedPiAiProviderProfile["piProvider"],
+	retryPolicy?: RetryPolicyConfig | undefined,
+	headers?: Record<string, string> | undefined,
+): ResolvedPiAiProviderProfile {
+	return {
+		provider,
+		displayName,
+		streamIdleTimeoutMs: GROK_BUILD_STREAM_IDLE_TIMEOUT_MS,
+		retryPolicy: resolveRetryPolicy(
+			retryPolicy ?? CODING_OAUTH_RETRY_POLICY,
+			"dsh-coding-subscription-oauth retryPolicy",
+		),
+		configuredMaxTokens: new Map(),
+		...(headers === undefined ? {} : { headers }),
+		piProvider,
+	};
+}
+
+/** Existing Grok-only constructor retained for public API compatibility. */
+export function createGrokBuildAdapter(
+	session: GrokBuildSession,
+	resolveAttachments: () => AttachmentStore | undefined,
+): PiAiAdapter {
+	return new PiAiAdapter({
+		profiles: () =>
+			new Map<string, ResolvedPiAiProviderProfile>([
+				[
+					GROK_BUILD_ROUTE,
+					profile(GROK_BUILD_ROUTE, "xAI Grok Build", session.provider(), undefined, grokBuildFingerprintHeaders()),
+				],
+			]),
+		resolveApiKey: async () =>
+			resolveOAuthToken("Grok Build", async () => {
+				const auth = await session.models.getAuth(XAI_PI_PROVIDER, { minOAuthValidityMs: MIN_OAUTH_VALIDITY_MS });
+				return auth?.auth.apiKey;
+			}),
+		resolveAttachments,
+	});
+}
+
+/** Opt-in Codex Fast wiring; ordinary `codex-oauth` is unchanged when this is omitted. */
+export interface CodingOAuthAdapterOptions {
+	retryPolicy?: RetryPolicyConfig;
+	codexFast?: { isEligible(modelId: string): boolean };
+}
+
+function isRetryPolicyConfig(value: object): value is RetryPolicyConfig {
+	return "mode" in value;
+}
+
+function splitCodingOAuthAdapterArgs(
+	fourth?: RetryPolicyConfig | CodingOAuthAdapterOptions,
+	fifth?: CodingOAuthAdapterOptions,
+): CodingOAuthAdapterOptions {
+	if (fifth !== undefined) {
+		return {
+			...(fourth !== undefined && isRetryPolicyConfig(fourth) ? { retryPolicy: fourth } : {}),
+			...fifth,
+		};
+	}
+	if (fourth === undefined) return {};
+	if (isRetryPolicyConfig(fourth)) return { retryPolicy: fourth };
+	return {
+		...(fourth.retryPolicy === undefined ? {} : { retryPolicy: fourth.retryPolicy }),
+		...(fourth.codexFast === undefined ? {} : { codexFast: fourth.codexFast }),
+	};
+}
+
+/** Create the four-route OAuth adapter while preserving each pi-ai native id. */
+export function createCodingOAuthAdapter(
+	grok: GrokBuildSession,
+	subscriptions: readonly OAuthProviderSession[],
+	resolveAttachments: () => AttachmentStore | undefined,
+	retryPolicy?: RetryPolicyConfig,
+	options?: CodingOAuthAdapterOptions,
+): LlmAdapter;
+export function createCodingOAuthAdapter(
+	grok: GrokBuildSession,
+	subscriptions: readonly OAuthProviderSession[],
+	resolveAttachments: () => AttachmentStore | undefined,
+	options?: CodingOAuthAdapterOptions,
+): LlmAdapter;
+export function createCodingOAuthAdapter(
+	grok: GrokBuildSession,
+	subscriptions: readonly OAuthProviderSession[],
+	resolveAttachments: () => AttachmentStore | undefined,
+	retryPolicyOrOptions?: RetryPolicyConfig | CodingOAuthAdapterOptions,
+	options?: CodingOAuthAdapterOptions,
+): LlmAdapter {
+	const { retryPolicy, codexFast } = splitCodingOAuthAdapterArgs(retryPolicyOrOptions, options);
+	const byNativeId = new Map(subscriptions.map((session) => [session.definition.nativeProviderId, session]));
+	const codexSession = byNativeId.get(CODEX_PI_PROVIDER);
+	const aliases = new Map<string, string>([
+		[GROK_BUILD_ROUTE, GROK_BUILD_ROUTE],
+		[CODEX_OAUTH_ROUTE, CODEX_PI_PROVIDER],
+		[KIMI_CODE_OAUTH_ROUTE, KIMI_PI_PROVIDER],
+		[CLAUDE_CODE_OAUTH_ROUTE, CLAUDE_PI_PROVIDER],
+	]);
+	if (codexFast !== undefined && codexSession !== undefined) {
+		aliases.set(CODEX_OAUTH_FAST_ROUTE, CODEX_OAUTH_FAST_ROUTE);
+	}
+	const policies = new Map<string, AliasLlmRoutePolicy>([
+		[
+			GROK_BUILD_ROUTE,
+			{
+				displayName: "xAI Grok Build (OAuth)",
+				isAuthenticated: async () => (await grok.store.read(XAI_PI_PROVIDER))?.type === "oauth",
+				onAuthFailure: () => grok.invalidateAccessToken(),
+			},
+		],
+	]);
+	for (const session of subscriptions) {
+		policies.set(session.definition.route, {
+			displayName: `${session.definition.displayName.replace(/\s*\([^)]*\)$/u, "")} (OAuth)`,
+			isAuthenticated: async () => (await session.status()).authenticated,
+			onAuthFailure: () => session.invalidateAccessToken(),
+		});
+	}
+	if (codexFast !== undefined && codexSession !== undefined) {
+		policies.set(CODEX_OAUTH_FAST_ROUTE, {
+			displayName: "OpenAI Codex Fast requested (OAuth)",
+			isAuthenticated: async () => (await codexSession.status()).authenticated,
+			includeModel: (modelId) => codexFast.isEligible(modelId),
+			onAuthFailure: () => codexSession.invalidateAccessToken(),
+		});
+	}
+
+	const inner = new PiAiAdapter({
+		profiles: () => {
+			const profiles = new Map<string, ResolvedPiAiProviderProfile>();
+			profiles.set(
+				GROK_BUILD_ROUTE,
+				profile(GROK_BUILD_ROUTE, "xAI Grok Build", grok.provider(), retryPolicy, grokBuildFingerprintHeaders()),
+			);
+			for (const session of subscriptions) {
+				profiles.set(
+					session.definition.nativeProviderId,
+					profile(session.definition.nativeProviderId, session.definition.displayName, session.provider(), retryPolicy),
+				);
+			}
+			if (codexFast !== undefined && codexSession !== undefined) {
+				const wrapped = withCodexFastRouting(codexSession.provider(), {
+					isEligible: (modelId) => codexFast.isEligible(modelId),
+					profileProviderId: CODEX_OAUTH_FAST_ROUTE,
+					nativeProviderId: CODEX_PI_PROVIDER,
+				});
+				// Models.streamSimple dispatches on model.provider. Advertise the Fast
+				// profile id on the catalog so the wrapper runs, then restore native
+				// identity inside withCodexFastRouting before the wire call.
+				const fastProvider = {
+					...wrapped,
+					getModels: () =>
+						wrapped
+							.getModels()
+							.map((model) =>
+								model.provider === CODEX_OAUTH_FAST_ROUTE ? model : { ...model, provider: CODEX_OAUTH_FAST_ROUTE },
+							),
+				};
+				profiles.set(
+					CODEX_OAUTH_FAST_ROUTE,
+					profile(
+						CODEX_OAUTH_FAST_ROUTE,
+						"OpenAI Codex Fast requested",
+						fastProvider as unknown as ResolvedPiAiProviderProfile["piProvider"],
+						retryPolicy,
+					),
+				);
+			}
+			return profiles;
+		},
+		resolveApiKey: async (provider) => {
+			if (provider === GROK_BUILD_ROUTE) {
+				return resolveOAuthToken("Grok Build", async () => {
+					const auth = await grok.models.getAuth(XAI_PI_PROVIDER, { minOAuthValidityMs: MIN_OAUTH_VALIDITY_MS });
+					return auth?.auth.apiKey;
+				});
+			}
+			const session =
+				provider === CODEX_OAUTH_FAST_ROUTE ? byNativeId.get(CODEX_PI_PROVIDER) : byNativeId.get(provider);
+			if (session === undefined) throw new LlmError(`Unknown OAuth provider "${provider}"`, "NO_ADAPTER");
+			return resolveOAuthToken(session.definition.displayName, () => session.resolveAccessToken());
+		},
+		resolveAttachments,
+	});
+
+	return new AliasLlmAdapter(inner, aliases, policies);
+}
+
+/**
+ * Resolve an OAuth access token for one route, translating a failed refresh
+ * (revoked refresh token, dead grant) into MISSING_CREDENTIAL so the failure
+ * is not retried and the user is told to sign in again rather than shown a
+ * bare upstream 401.
+ */
+async function resolveOAuthToken(
+	displayName: string,
+	getAccessToken: () => Promise<string | undefined>,
+): Promise<string> {
+	let accessToken: string | undefined;
+	try {
+		accessToken = await getAccessToken();
+	} catch (error) {
+		throw new LlmError(
+			`${displayName} could not refresh its sign-in (${safeMessage(error)}).` +
+				" Open Settings → Coding OAuth and sign in again.",
+			"MISSING_CREDENTIAL",
+		);
+	}
+	if (accessToken === undefined || accessToken.length === 0) return missingCredential(displayName);
+	return accessToken;
+}

package/src/alias-adapter.ts

@@ -0,0 +1,152 @@
+/**
+ * Harness route aliases over a native-id PiAiAdapter.
+ * @module dsh-coding-subscription-oauth/alias-adapter
+ */
+
+import type {
+	GenerateOptions,
+	LlmModelInfo,
+	LlmProviderInfo,
+	LlmResolvedModelInfo,
+	ResolvedRetryPolicy,
+	StreamChunk,
+} from "@deepseek-ai/dsh-llm";
+import { LlmAdapter, LlmError } from "@deepseek-ai/dsh-llm";
+import { remapAuthFailureIfContextOverflow } from "./kimi-errors.ts";
+
+export interface AliasLlmRoutePolicy {
+	/** User-facing provider name shown above models in the model selector. */
+	displayName?: string;
+	/** Return false to hide every model for this route from discovery. */
+	isAuthenticated?: () => Promise<boolean>;
+	/**
+	 * After authentication, keep only models this predicate accepts.
+	 * Used by opt-in routes (e.g. Codex Fast) so ineligible ids stay hidden
+	 * without hiding the whole authenticated catalog.
+	 */
+	includeModel?: (modelId: string) => boolean;
+	/**
+	 * Called once when a stream for this route finishes with an AUTH failure
+	 * (upstream rejected a locally-valid token). Implementations backdate the
+	 * stored credential's expiry so the retried step refreshes before reuse.
+	 * Awaiting it here keeps invalidation ordered before the retry executor
+	 * reruns the step; failures are swallowed so the original AUTH surfaces.
+	 */
+	onAuthFailure?: () => Promise<void>;
+}
+
+function routePiAiReplayState(value: unknown, route: string): unknown {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+	const state = value as Record<string, unknown>;
+	if (state["kind"] !== "pi-ai" || state["provider"] === route) return value;
+	return { ...state, provider: route };
+}
+
+function normalizeReplayForRoute(
+	message: GenerateOptions["messages"][number],
+	route: string,
+): GenerateOptions["messages"][number] {
+	if (message.role !== "assistant" || message.source.kind !== "model") return message;
+	if (message.source.provider !== route) {
+		if (message.source.replayState === undefined) return message;
+		const { replayState: _foreignReplay, ...source } = message.source;
+		return { ...message, source };
+	}
+	const replayState = routePiAiReplayState(message.source.replayState, route);
+	if (replayState === message.source.replayState) return message;
+	return { ...message, source: { ...message.source, replayState } };
+}
+
+/**
+ * Keeps pi-ai model.provider identities native while exposing collision-free
+ * Harness route names. Every public operation translates exactly once.
+ */
+export class AliasLlmAdapter extends LlmAdapter {
+	constructor(
+		private readonly inner: LlmAdapter,
+		private readonly aliases: ReadonlyMap<string, string>,
+		private readonly policies: ReadonlyMap<string, AliasLlmRoutePolicy> = new Map(),
+	) {
+		super();
+	}
+
+	private nativeProvider(route: string): string {
+		const provider = this.aliases.get(route);
+		if (provider === undefined) throw new LlmError(`OAuth adapter does not own provider "${route}"`, "NO_ADAPTER");
+		return provider;
+	}
+
+	providerInfo(provider: string): LlmProviderInfo {
+		const native = this.nativeProvider(provider);
+		const info = this.inner.providerInfo(native);
+		const displayName = this.policies.get(provider)?.displayName;
+		return { ...info, id: provider, ...(displayName === undefined ? {} : { name: displayName }) };
+	}
+
+	providerRetryPolicy(provider: string): ResolvedRetryPolicy | undefined {
+		return this.inner.providerRetryPolicy(this.nativeProvider(provider));
+	}
+
+	async listModels(provider: string): Promise<readonly LlmModelInfo[]> {
+		const native = this.nativeProvider(provider);
+		const isAuthenticated = this.policies.get(provider)?.isAuthenticated;
+		if (isAuthenticated !== undefined) {
+			try {
+				if (!(await isAuthenticated())) return [];
+			} catch {
+				// A corrupt/unreadable credential must hide models instead of breaking
+				// the entire model picker or presenting a route that cannot be used.
+				return [];
+			}
+		}
+		const listed = (await this.inner.listModels(native)).map((model) => ({ ...model, provider }));
+		const includeModel = this.policies.get(provider)?.includeModel;
+		return includeModel === undefined ? listed : listed.filter((model) => includeModel(model.id));
+	}
+
+	async resolveModel(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo> {
+		const native = this.nativeProvider(provider);
+		return { ...(await this.inner.resolveModel(native, model, signal)), provider };
+	}
+
+	async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+		const route = options.provider;
+		const native = this.nativeProvider(route);
+		const messages = options.messages.map((message) => normalizeReplayForRoute(message, route));
+		let authFailureNotified = false;
+		for await (const raw of this.inner.stream({ ...options, provider: native, messages })) {
+			const chunk =
+				raw.type === "finish" && raw.reason.kind === "error"
+					? {
+							...raw,
+							reason: {
+								...raw.reason,
+								failure: remapAuthFailureIfContextOverflow(raw.reason.failure),
+							},
+						}
+					: raw;
+			if (
+				!authFailureNotified &&
+				chunk.type === "finish" &&
+				chunk.reason.kind === "error" &&
+				chunk.reason.failure.code === "AUTH"
+			) {
+				authFailureNotified = true;
+				const onAuthFailure = this.policies.get(route)?.onAuthFailure;
+				if (onAuthFailure !== undefined) {
+					try {
+						await onAuthFailure();
+					} catch {
+						// Invalidation is best-effort: the original AUTH failure must
+						// surface unchanged even when the credential store is unreadable.
+					}
+				}
+			}
+			if (chunk.type === "finish" && chunk.replayState !== undefined) {
+				yield { ...chunk, replayState: routePiAiReplayState(chunk.replayState, route) };
+			} else {
+				yield chunk;
+			}
+		}
+	}
+}