dsh-coding-subscription-oauth 0.5.0

package/src/codex-model-capabilities.ts

@@ -0,0 +1,320 @@
+/**
+ * Live Codex model service-tier cache and composable fast-route payload helpers.
+ *
+ * Fetches `GET /backend-api/codex/models?client_version=…`, caches `service_tiers`,
+ * and never invents eligibility when the live catalog is missing or stale.
+ * A stale TTL is unknown: Fast is default-deny until a live, non-stale catalog
+ * explicitly lists `priority` for that model. `isEligible` is required and
+ * fail-closed — omitting it or returning false injects nothing.
+ *
+ * Ordinary inference stays unchanged: the unwrapped provider is never mutated.
+ * A wrapper may use a distinct profile provider id (`codex-oauth-fast`) while
+ * restoring native `model.provider` for the base wire call and the same catalog.
+ *
+ * @module dsh-coding-subscription-oauth/codex-model-capabilities
+ */
+
+import {
+	type CodexAuthSession,
+	type CodexFetch,
+	type CodexHttpClient,
+	createCodexHttpClient,
+	isRecord,
+	optionalNonEmptyString,
+} from "./codex-http.ts";
+import { CODEX_OAUTH_FAST_ROUTE } from "./ids.ts";
+
+/** Distinct optional Harness route; parent owns dynamic registration. */
+export { CODEX_OAUTH_FAST_ROUTE };
+
+export const CODEX_MODELS_URL = "https://chatgpt.com/backend-api/codex/models";
+export const DEFAULT_CODEX_CLIENT_VERSION = "0.144.0";
+export const DEFAULT_CODEX_SERVICE_TIER = "priority";
+export const CODEX_ROUTING_HINT_HEADER = "x-codex-routing-hint";
+
+const DEFAULT_TTL_MS = 15 * 60 * 1000;
+
+export interface CodexModelCapability {
+	readonly id: string;
+	readonly serviceTiers: readonly string[];
+}
+
+export interface CodexModelCapabilitiesOptions {
+	readonly auth: CodexAuthSession;
+	readonly http?: CodexHttpClient;
+	readonly fetchImpl?: CodexFetch;
+	readonly clientVersion?: string;
+	readonly originator?: string;
+	readonly userAgent?: string;
+	readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+	readonly now?: () => number;
+	readonly ttlMs?: number;
+}
+
+export interface CodexModelCapabilities {
+	refresh(signal?: AbortSignal): Promise<readonly CodexModelCapability[]>;
+	clear(): void;
+	getCached(): readonly CodexModelCapability[] | undefined;
+	serviceTiers(modelId: string): readonly string[];
+	isPriorityEligible(modelId: string): boolean;
+	isTierEligible(modelId: string, tier: string): boolean;
+}
+
+export type CodexOnPayload = (payload: unknown, model: unknown) => unknown | undefined | Promise<unknown | undefined>;
+
+export interface CodexFastStreamOptions {
+	onPayload?: CodexOnPayload;
+	headers?: Record<string, string | null>;
+	[key: string]: unknown;
+}
+
+/**
+ * Fast-route composition is default-deny.
+ * `isEligible` is required; missing or false means no header and no `service_tier`.
+ */
+export interface CodexFastRoutingOptions {
+	readonly isEligible: (modelId: string) => boolean;
+	readonly serviceTier?: string;
+	/** Distinct profile/route id for the wrapper (e.g. {@link CODEX_OAUTH_FAST_ROUTE}). */
+	readonly profileProviderId?: string;
+	/** Native provider id restored on `model.provider` before the base wire call. */
+	readonly nativeProviderId?: string;
+}
+
+export interface CodexStreamModel {
+	readonly id: string;
+	readonly provider?: string;
+	readonly [key: string]: unknown;
+}
+
+/** Structural pi-ai provider face; `never` parameters keep native Provider assignable. */
+export interface CodexStreamableProvider {
+	readonly id: string;
+	readonly headers?: Record<string, string | null>;
+	stream: (model: never, context: never, options?: never) => unknown;
+	streamSimple: (model: never, context: never, options?: never) => unknown;
+}
+
+/** Wrapper face with callable stream methods and a possibly distinct profile id. */
+export type CodexFastWrappedProvider<P extends CodexStreamableProvider> = Omit<
+	P,
+	"id" | "headers" | "stream" | "streamSimple"
+> & {
+	readonly id: string;
+	readonly headers?: Record<string, string | null>;
+	stream: (model: CodexStreamModel, context: unknown, options?: CodexFastStreamOptions) => unknown;
+	streamSimple: (model: CodexStreamModel, context: unknown, options?: CodexFastStreamOptions) => unknown;
+};
+
+function parseServiceTiers(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	const tiers: string[] = [];
+	const seen = new Set<string>();
+	for (const item of value) {
+		const id =
+			typeof item === "string"
+				? optionalNonEmptyString(item)
+				: isRecord(item)
+					? optionalNonEmptyString(item["id"])
+					: undefined;
+		if (id === undefined || seen.has(id)) continue;
+		seen.add(id);
+		tiers.push(id);
+	}
+	return tiers;
+}
+
+/** Parse the live models envelope. Unknown shapes yield an empty catalog, never a hardcoded fallback. */
+export function parseCodexModelCapabilities(value: unknown): CodexModelCapability[] {
+	if (!isRecord(value)) return [];
+	const raw = value["models"];
+	if (!Array.isArray(raw)) return [];
+	const models: CodexModelCapability[] = [];
+	const seen = new Set<string>();
+	for (const item of raw) {
+		if (!isRecord(item)) continue;
+		const id = optionalNonEmptyString(item["slug"]) ?? optionalNonEmptyString(item["id"]);
+		if (id === undefined || seen.has(id)) continue;
+		seen.add(id);
+		models.push({ id, serviceTiers: parseServiceTiers(item["service_tiers"]) });
+	}
+	return models;
+}
+
+export function codexModelsUrl(clientVersion: string): string {
+	const url = new URL(CODEX_MODELS_URL);
+	url.searchParams.set("client_version", clientVersion);
+	return url.toString();
+}
+
+/** Exact per-model Fast header value. Never a bare static `priority`. */
+export function codexRoutingHint(modelId: string, tier = DEFAULT_CODEX_SERVICE_TIER): string {
+	return `model=${modelId};tier=${tier}`;
+}
+
+function modelIdOf(payload: unknown, model: unknown): string | undefined {
+	if (isRecord(model)) {
+		const id = optionalNonEmptyString(model["id"]);
+		if (id !== undefined) return id;
+	}
+	return isRecord(payload) ? optionalNonEmptyString(payload["model"]) : undefined;
+}
+
+function isFastEligible(options: CodexFastRoutingOptions | undefined, modelId: string): boolean {
+	return options?.isEligible?.(modelId) === true;
+}
+
+function restoreNativeProvider(model: CodexStreamModel, nativeProviderId: string): CodexStreamModel {
+	if (model.provider === nativeProviderId) return model;
+	return { ...model, provider: nativeProviderId };
+}
+
+/**
+ * Compose an existing `onPayload` with service_tier injection.
+ * Does not override a payload that already set `service_tier`.
+ * Fail-closed: injection happens only when `isEligible(modelId)` is exactly true.
+ */
+export function composeCodexFastOnPayload(
+	inner: CodexOnPayload | undefined,
+	options: CodexFastRoutingOptions,
+): CodexOnPayload {
+	const serviceTier = options.serviceTier ?? DEFAULT_CODEX_SERVICE_TIER;
+	return async (payload, model) => {
+		const next = inner === undefined ? payload : await inner(payload, model);
+		const body = next === undefined ? payload : next;
+		if (!isRecord(body)) return next;
+		const modelId = modelIdOf(body, model);
+		if (modelId === undefined || !isFastEligible(options, modelId)) return next;
+		if (optionalNonEmptyString(body["service_tier"]) !== undefined) return next;
+		return { ...body, service_tier: serviceTier };
+	};
+}
+
+/** Merge `x-codex-routing-hint=model=<slug>;tier=<tier>` without dropping existing keys. */
+export function composeCodexFastHeaders(
+	headers: Record<string, string | null> | undefined,
+	modelId: string,
+	tier = DEFAULT_CODEX_SERVICE_TIER,
+): Record<string, string | null> {
+	return { ...(headers ?? {}), [CODEX_ROUTING_HINT_HEADER]: codexRoutingHint(modelId, tier) };
+}
+
+/** Apply fast-route payload + per-model header composition to one stream-options object. */
+export function applyCodexFastStreamOptions<T extends CodexFastStreamOptions>(
+	options: T | undefined,
+	config: CodexFastRoutingOptions,
+	modelId: string,
+): T {
+	const eligible = isFastEligible(config, modelId);
+	const tier = config.serviceTier ?? DEFAULT_CODEX_SERVICE_TIER;
+	const onPayload = eligible
+		? composeCodexFastOnPayload(options?.onPayload, { ...config, isEligible: () => true })
+		: options?.onPayload;
+	const next: CodexFastStreamOptions = {
+		...(options ?? {}),
+		...(onPayload === undefined ? {} : { onPayload }),
+		headers: eligible ? composeCodexFastHeaders(options?.headers, modelId, tier) : { ...(options?.headers ?? {}) },
+	};
+	return next as T;
+}
+
+/**
+ * Wrap a pi-ai provider for a future `codex-oauth-fast` route.
+ * The original provider object is not mutated. The wrapper may advertise a
+ * distinct profile provider id while restoring native `model.provider` so the
+ * base wire call and model catalog stay on the native provider.
+ */
+export function withCodexFastRouting<P extends CodexStreamableProvider>(
+	provider: P,
+	options: CodexFastRoutingOptions,
+): CodexFastWrappedProvider<P> {
+	const nativeProviderId = options.nativeProviderId ?? provider.id;
+	const profileProviderId = options.profileProviderId ?? provider.id;
+
+	const forward =
+		(method: "stream" | "streamSimple") =>
+		(model: CodexStreamModel, context: unknown, streamOptions?: CodexFastStreamOptions) => {
+			const wireModel = restoreNativeProvider(model, nativeProviderId);
+			return provider[method](
+				wireModel as never,
+				context as never,
+				applyCodexFastStreamOptions(streamOptions, options, model.id) as never,
+			);
+		};
+
+	return {
+		...provider,
+		id: profileProviderId,
+		stream: forward("stream"),
+		streamSimple: forward("streamSimple"),
+	};
+}
+
+/**
+ * Live `/codex/models` cache. Fetch failures leave ordinary inference alone.
+ * Eligibility is false until a live, non-stale catalog explicitly lists the tier.
+ * A stale TTL is treated as unknown, not as the last known catalog.
+ */
+export function createCodexModelCapabilities(options: CodexModelCapabilitiesOptions): CodexModelCapabilities {
+	const http =
+		options.http ??
+		createCodexHttpClient({
+			auth: options.auth,
+			...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+			...(options.originator === undefined ? {} : { originator: options.originator }),
+			...(options.userAgent === undefined ? {} : { userAgent: options.userAgent }),
+			...(options.sleep === undefined ? {} : { sleep: options.sleep }),
+			...(options.now === undefined ? {} : { now: options.now }),
+		});
+	const clientVersion = options.clientVersion ?? DEFAULT_CODEX_CLIENT_VERSION;
+	const now = options.now ?? Date.now;
+	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+	let cached: { fetchedAt: number; models: readonly CodexModelCapability[] } | undefined;
+	let inFlight: Promise<readonly CodexModelCapability[]> | undefined;
+	let epoch = 0;
+
+	const isFresh = (): boolean => cached !== undefined && now() - cached.fetchedAt < ttlMs;
+
+	const freshModels = (): readonly CodexModelCapability[] | undefined => (isFresh() ? cached?.models : undefined);
+
+	const lookup = (modelId: string): CodexModelCapability | undefined =>
+		freshModels()?.find((model) => model.id === modelId);
+
+	const load = async (startedEpoch: number, signal?: AbortSignal): Promise<readonly CodexModelCapability[]> => {
+		try {
+			const payload = await http.requestJson({
+				url: codexModelsUrl(clientVersion),
+				method: "GET",
+				headers: { "cache-control": "no-store" },
+				...(signal === undefined ? {} : { signal }),
+			});
+			const models = parseCodexModelCapabilities(payload);
+			if (startedEpoch === epoch) cached = { fetchedAt: now(), models };
+			return models;
+		} catch {
+			return freshModels() ?? [];
+		}
+	};
+
+	return {
+		async refresh(signal) {
+			if (isFresh() && cached !== undefined) return cached.models;
+			if (inFlight !== undefined) return inFlight;
+			const startedEpoch = epoch;
+			const current = load(startedEpoch, signal).finally(() => {
+				if (inFlight === current) inFlight = undefined;
+			});
+			inFlight = current;
+			return current;
+		},
+		clear() {
+			epoch += 1;
+			cached = undefined;
+			inFlight = undefined;
+		},
+		getCached: () => freshModels(),
+		serviceTiers: (modelId) => lookup(modelId)?.serviceTiers ?? [],
+		isPriorityEligible: (modelId) => lookup(modelId)?.serviceTiers.includes(DEFAULT_CODEX_SERVICE_TIER) === true,
+		isTierEligible: (modelId, tier) => lookup(modelId)?.serviceTiers.includes(tier) === true,
+	};
+}

package/src/codex-search.ts

@@ -0,0 +1,245 @@
+/**
+ * Optional Codex subscription search against the private ChatGPT backend.
+ * Default-off: parent registers the returned provider only when the user enables it.
+ *
+ * @module dsh-coding-subscription-oauth/codex-search
+ */
+
+import { LlmError } from "@deepseek-ai/dsh-llm";
+import {
+	type CodexAuthSession,
+	type CodexFetch,
+	type CodexHttpClient,
+	createCodexHttpClient,
+	isRecord,
+	optionalNonEmptyString,
+} from "./codex-http.ts";
+
+/** Stable search-provider id. Parent must not write this into `web.searchProvider` by default. */
+export const CODEX_SEARCH_PROVIDER_ID = "codex-oauth-search";
+
+/** Official Codex standalone search endpoint. */
+export const CODEX_SEARCH_URL = "https://chatgpt.com/backend-api/codex/alpha/search";
+
+export const CODEX_SEARCH_CONTEXT_SIZES = ["low", "medium", "high"] as const;
+export type CodexSearchContextSize = (typeof CODEX_SEARCH_CONTEXT_SIZES)[number];
+
+export const CODEX_SEARCH_MODES = ["live", "cached", "indexed"] as const;
+export type CodexSearchMode = (typeof CODEX_SEARCH_MODES)[number];
+
+export type CodexExternalWebAccess = true | false | "indexed";
+
+export interface CodexSearchSource {
+	readonly url: string;
+	readonly title?: string;
+	readonly snippet?: string;
+}
+
+export interface CodexSearchRequest {
+	readonly query: string;
+	readonly maxResults?: number;
+}
+
+export interface CodexSearchResult {
+	readonly content?: string;
+	readonly sources: readonly CodexSearchSource[];
+	readonly truncated: boolean;
+}
+
+export interface CodexSearchRequestBody {
+	readonly id: string;
+	readonly model: string;
+	readonly input: readonly [
+		{
+			readonly type: "message";
+			readonly role: "user";
+			readonly content: readonly [{ readonly type: "input_text"; readonly text: string }];
+		},
+	];
+	readonly commands: {
+		readonly search_query: readonly [{ readonly q: string }];
+	};
+	readonly settings: {
+		readonly search_context_size: CodexSearchContextSize;
+		readonly allowed_callers: readonly ["direct"];
+		readonly external_web_access: CodexExternalWebAccess;
+	};
+	readonly max_output_tokens: number;
+}
+
+export interface CodexSearchProviderOptions {
+	readonly auth: CodexAuthSession;
+	readonly http?: CodexHttpClient;
+	readonly fetchImpl?: CodexFetch;
+	/** Current visible Codex model, or a live resolver for catalog/login changes. */
+	readonly model: string | (() => string);
+	readonly mode?: CodexSearchMode;
+	readonly contextSize?: CodexSearchContextSize;
+	readonly maxOutputTokens?: number;
+	readonly resolveRequestId?: () => string;
+	readonly originator?: string;
+	readonly userAgent?: string;
+	readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+/** Structural `WebSearchProvider` so parent can register without this module importing dsh-web. */
+export interface CodexSearchProvider {
+	readonly id: typeof CODEX_SEARCH_PROVIDER_ID;
+	available(): boolean;
+	search(request: CodexSearchRequest, signal?: AbortSignal): Promise<CodexSearchResult>;
+}
+
+const DEFAULT_CONTEXT_SIZE: CodexSearchContextSize = "medium";
+const DEFAULT_MODE: CodexSearchMode = "live";
+const DEFAULT_MAX_OUTPUT_TOKENS = 1024;
+
+/** Map configured search mode onto the verified `external_web_access` field. */
+export function externalWebAccess(mode: CodexSearchMode): CodexExternalWebAccess {
+	switch (mode) {
+		case "cached":
+			return false;
+		case "indexed":
+			return "indexed";
+		case "live":
+			return true;
+	}
+}
+
+/** Accept only citeable http(s) URLs. */
+export function citeableHttpUrl(value: unknown): string | undefined {
+	if (typeof value !== "string" || value.length === 0) return undefined;
+	try {
+		const url = new URL(value);
+		if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+		if (url.username !== "" || url.password !== "") return undefined;
+		return value;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Reject `<1` / non-finite `maxResults` rather than treating them as unlimited. */
+export function assertCodexSearchMaxResults(maxResults: number | undefined): void {
+	if (maxResults === undefined) return;
+	if (!Number.isFinite(maxResults) || maxResults < 1) {
+		throw new LlmError("Codex search maxResults must be a finite number of at least 1", "INVALID_ARGS");
+	}
+}
+
+/**
+ * Map the standalone endpoint's forward-compatible result DTOs.
+ * Only `type === "text_result"` items with valid http(s) URLs are kept; URLs are de-duplicated.
+ */
+export function mapCodexSearchResponse(value: unknown, maxResults?: number): CodexSearchResult {
+	assertCodexSearchMaxResults(maxResults);
+	if (!isRecord(value) || typeof value["output"] !== "string") {
+		throw new LlmError("Codex returned a search response without string output", "SERVER");
+	}
+	const output = value["output"];
+	const rawResults = value["results"];
+	if (rawResults !== undefined && !Array.isArray(rawResults)) {
+		throw new LlmError("Codex returned a search response with non-array results", "SERVER");
+	}
+	const sources: CodexSearchSource[] = [];
+	const seen = new Set<string>();
+	for (const item of rawResults ?? []) {
+		if (!isRecord(item) || item["type"] !== "text_result") continue;
+		const url = citeableHttpUrl(item["url"]);
+		if (url === undefined || seen.has(url)) continue;
+		seen.add(url);
+		const title = optionalNonEmptyString(item["title"]);
+		const snippet = optionalNonEmptyString(item["snippet"]);
+		sources.push({
+			url,
+			...(title === undefined ? {} : { title }),
+			...(snippet === undefined ? {} : { snippet }),
+		});
+	}
+	const limited = maxResults === undefined ? sources : sources.slice(0, maxResults);
+	return {
+		...(output.length === 0 ? {} : { content: output }),
+		sources: limited,
+		truncated: limited.length < sources.length,
+	};
+}
+
+export function buildCodexSearchRequestBody(
+	query: string,
+	options: {
+		id: string;
+		model: string;
+		mode: CodexSearchMode;
+		contextSize: CodexSearchContextSize;
+		maxOutputTokens: number;
+	},
+): CodexSearchRequestBody {
+	return {
+		id: options.id,
+		model: options.model,
+		input: [
+			{
+				type: "message",
+				role: "user",
+				content: [{ type: "input_text", text: query }],
+			},
+		],
+		commands: { search_query: [{ q: query }] },
+		settings: {
+			search_context_size: options.contextSize,
+			allowed_callers: ["direct"],
+			external_web_access: externalWebAccess(options.mode),
+		},
+		max_output_tokens: options.maxOutputTokens,
+	};
+}
+
+/** Factory for an injectable, default-off Codex search provider. */
+export function createCodexSearchProvider(options: CodexSearchProviderOptions): CodexSearchProvider {
+	const http =
+		options.http ??
+		createCodexHttpClient({
+			auth: options.auth,
+			...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+			...(options.originator === undefined ? {} : { originator: options.originator }),
+			...(options.userAgent === undefined ? {} : { userAgent: options.userAgent }),
+			...(options.sleep === undefined ? {} : { sleep: options.sleep }),
+		});
+	const mode = options.mode ?? DEFAULT_MODE;
+	const contextSize = options.contextSize ?? DEFAULT_CONTEXT_SIZE;
+	const maxOutputTokens = options.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
+	const resolveRequestId = options.resolveRequestId ?? (() => crypto.randomUUID());
+	const configuredModel = options.model;
+	const resolveModel: () => string = typeof configuredModel === "function" ? configuredModel : () => configuredModel;
+	const available = (): boolean =>
+		resolveModel().trim().length > 0 && Number.isInteger(maxOutputTokens) && maxOutputTokens > 0;
+
+	return {
+		id: CODEX_SEARCH_PROVIDER_ID,
+		available,
+		async search(request, signal) {
+			const query = request.query.trim();
+			if (query.length === 0) {
+				throw new LlmError("Codex search requires a non-empty query", "INVALID_ARGS");
+			}
+			assertCodexSearchMaxResults(request.maxResults);
+			const model = resolveModel().trim();
+			if (model.length === 0 || !Number.isInteger(maxOutputTokens) || maxOutputTokens <= 0) {
+				throw new LlmError("Codex search is not configured", "INVALID_ARGS");
+			}
+			const body = buildCodexSearchRequestBody(query, {
+				id: resolveRequestId(),
+				model,
+				mode,
+				contextSize,
+				maxOutputTokens,
+			});
+			const payload = await http.requestJson({
+				url: CODEX_SEARCH_URL,
+				method: "POST",
+				body,
+				...(signal === undefined ? {} : { signal }),
+			});
+			return mapCodexSearchResponse(payload, request.maxResults);
+		},
+	};
+}