dsh-coding-subscription-oauth 0.6.3 → 0.6.5

package/src/codex-model-capabilities.ts

@@ -1,320 +0,0 @@
-/**
- * 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

@@ -1,245 +0,0 @@
-/**
- * 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);
-		},
-	};
-}