@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
401 lines (382 loc) • 18 kB
text/typescript
import { contextTierRecordConfigError, modelCapabilitiesConfigError } from "../config/provider-validation";
import {
CliUsageError,
csv,
printData,
rejectArgs,
runCliAction,
runtimeRequest,
summaryLines,
takeBooleanOption,
takeFlag,
takeOption,
terminalSafeText,
type RuntimeApiDeps,
} from "./runtime-api";
import { interactiveConfirm } from "./interactive-confirm";
import { takeProviderEditSettings } from "./provider-settings";
import { printProviderReceipt, runProviderAction } from "./provider-result";
import { providerQuotaLine } from "./account-extended";
import { pinSponsorRows } from "../providers/sponsor-order";
import type { ProviderQuotaReportDto } from "./account-api";
interface ProviderQuotasDto {
generatedAt?: number;
reports?: ProviderQuotaReportDto[];
}
interface QuotaResetEventDto {
kind?: string;
scope?: string;
window?: string;
percentBefore?: number;
percentAfter?: number;
resetAt?: number;
detectedAt?: number;
}
interface QuotaResetsDto {
enabled?: boolean;
events?: QuotaResetEventDto[];
}
const USAGE = `Usage:
ocx provider edit <name> [--adapter <id>] [--base-url <url>] [--default-model <id|->]
[--auth-mode <key|forward|oauth|local|->] [--note <text|->]
[--api-key-transport <x-api-key|bearer|->]
[--headers <json>] [--enabled <on|off>] [--live-models <on|off>]
[--retain-models <id,id|->] [--model <id> --text-only]
[--xai-chat <on|off>] [--upstream-http-version <http1.1|->] [--fast <on|off>] [--context-window <tokens|->]
[--allow-private-network <on|off>] [--model-context-tier <model=default|long_context>] [--json]
ocx provider test <name> [--model <id> [--yes]] [--json]
ocx provider quota [--refresh] [--json]
ocx provider resets [--limit <n>] [--json]
ocx provider presets [--json]
ocx provider account-mode <pool|direct> [--json]
ocx provider selected <name> [--set <model,model...>] [--clear] [--json]
ocx provider keychain <name> [status|store|restore] [--json]`;
function cleared(value: string | undefined): string | undefined {
return value === "-" ? "" : value;
}
async function edit(argv: string[], deps: RuntimeApiDeps): Promise<number> {
const args = [...argv];
const name = args.shift()?.trim();
if (!name) throw new CliUsageError("provider name is required", USAGE);
const wantsJson = takeFlag(args, "--json");
const patch: Record<string, unknown> = takeProviderEditSettings(args);
const adapter = takeOption(args, "--adapter");
const baseUrl = takeOption(args, "--base-url");
const defaultModel = cleared(takeOption(args, "--default-model"));
const authMode = cleared(takeOption(args, "--auth-mode"));
const note = cleared(takeOption(args, "--note"));
const apiKeyTransport = cleared(takeOption(args, "--api-key-transport"));
const headers = takeOption(args, "--headers");
const retainModelsRaw = takeOption(args, "--retain-models");
const enabled = takeBooleanOption(args, "--enabled");
const liveModels = takeBooleanOption(args, "--live-models");
const allowPrivateNetwork = takeBooleanOption(args, "--allow-private-network");
const xaiChat = takeBooleanOption(args, "--xai-chat");
const contextTierValues: string[] = [];
for (;;) {
const value = takeOption(args, "--model-context-tier");
if (value === undefined) break;
contextTierValues.push(value);
}
const textOnly = takeFlag(args, "--text-only");
const capabilityModel = takeOption(args, "--model");
rejectArgs(args, USAGE);
if (textOnly || capabilityModel !== undefined) {
if (!textOnly || capabilityModel === undefined) throw new CliUsageError("--text-only and --model must be supplied together", USAGE);
const declaration = { [capabilityModel]: { inputModalities: ["text"] } };
const error = modelCapabilitiesConfigError(declaration);
if (error) throw new CliUsageError(error, USAGE);
patch.modelCapabilities = declaration;
}
if (contextTierValues.length) {
if (name !== "github-copilot") throw new CliUsageError("--model-context-tier is valid only for provider github-copilot", USAGE);
const tiers: Record<string, "default" | "long_context"> = Object.create(null);
for (const value of contextTierValues) {
const separator = value.indexOf("=");
const model = value.slice(0, separator);
const tier = value.slice(separator + 1);
if (separator < 1 || (tier !== "default" && tier !== "long_context"))
throw new CliUsageError("--model-context-tier must use model=default or model=long_context", USAGE);
tiers[model] = tier;
}
const error = contextTierRecordConfigError(tiers);
if (error) throw new CliUsageError(error, USAGE);
patch.modelContextTiers = tiers;
}
if (xaiChat !== undefined) {
if (name !== "xai") throw new CliUsageError("--xai-chat is valid only for provider xai", USAGE);
patch.xaiResponsesOptIn = !xaiChat;
}
if (adapter !== undefined) patch.adapter = adapter;
if (baseUrl !== undefined) patch.baseUrl = baseUrl;
if (defaultModel !== undefined) patch.defaultModel = defaultModel;
if (authMode !== undefined) patch.authMode = authMode;
if (note !== undefined) patch.note = note;
if (apiKeyTransport !== undefined) patch.apiKeyTransport = apiKeyTransport;
if (headers !== undefined) {
if (headers === "-") {
patch.headers = null;
} else {
let parsed: unknown;
try { parsed = JSON.parse(headers); } catch { throw new CliUsageError("--headers must be valid JSON"); }
if (parsed === null) {
patch.headers = null;
} else if (typeof parsed !== "object" || Array.isArray(parsed)) {
throw new CliUsageError("--headers must be a JSON object like {\"X-Custom\":\"value\"}");
} else {
patch.headers = parsed;
}
}
}
if (enabled !== undefined) patch.disabled = !enabled;
if (retainModelsRaw !== undefined) {
// `-` clears, matching the other `edit` scalars; test before csv() or it becomes ["-"].
patch.retainModels = retainModelsRaw.trim() === "-" ? null : csv(retainModelsRaw);
}
if (liveModels !== undefined) patch.liveModels = liveModels;
if (allowPrivateNetwork !== undefined) patch.allowPrivateNetwork = allowPrivateNetwork;
if (Object.keys(patch).length === 0) throw new CliUsageError("at least one edit option is required", USAGE);
const result = await runtimeRequest(`/api/providers?name=${encodeURIComponent(name)}`, {
method: "PATCH", redirect: "error",
body: JSON.stringify(patch),
}, deps);
return printProviderReceipt(result, wantsJson, "Provider edit");
}
interface CompletionTestDto {
applicable: boolean;
reason?: string;
detail?: string;
adapter?: string;
ok?: boolean;
wireModel?: string;
upstreamModel?: string | null;
modelComparison?: "match" | "mismatch" | "unknown";
comparisonNote?: "missing_metadata" | "conflicting_metadata";
ttftMs?: number | null;
totalLatencyMs?: number;
error?: { code: string; message: string; status?: number } | null;
}
async function testCompletion(name: string, model: string, yes: boolean, wantsJson: boolean, deps: RuntimeApiDeps): Promise<number> {
const input = deps.stdinImpl ?? process.stdin;
if (!yes && (wantsJson || !input.isTTY)) {
throw new CliUsageError("completion tests consume quota and may incur cost; --yes is required with --json or non-interactive input", USAGE);
}
const warning = terminalSafeText(`${name}: completion test for model ${model}. Warning: this sends an upstream request, consumes quota and may incur cost.`);
if (wantsJson) console.error(warning);
else console.log(warning);
if (!yes && !await interactiveConfirm({
question: "Run this completion test?", defaultYes: false, input: input as NodeJS.ReadStream,
})) {
console.log("cancelled");
return 1;
}
const result = await runtimeRequest<CompletionTestDto>(`/api/providers/test-completion?name=${encodeURIComponent(name)}`, {
method: "POST", redirect: "error", body: JSON.stringify({ model, confirm: true }),
}, deps);
if (result.applicable === false) {
printData(result, wantsJson, [
`${name}: not applicable — ${result.reason}`,
...(result.detail ? [`Detail: ${result.detail}`] : []),
...(result.adapter ? [`Adapter: ${result.adapter}`] : []),
]);
return 0;
}
if (result.ok === true) {
printData(result, wantsJson, [
`${name}: connected`,
`TTFT: ${result.ttftMs ?? "unknown"} ms`,
`Total latency: ${result.totalLatencyMs ?? "unknown"} ms`,
`Upstream reported ${result.upstreamModel ?? "unknown"} for ${result.wireModel} — ${result.modelComparison}${result.comparisonNote ? ` (${result.comparisonNote})` : ""}`,
"metadata only — not proof of model identity",
]);
return 0;
}
printData(result, wantsJson, [
`${name}: failed`,
`${result.error?.code ?? "unknown"}: ${result.error?.message ?? "Completion test failed"}${result.error?.status === undefined ? "" : ` (HTTP ${result.error.status})`}`,
]);
return 1;
}
async function testProvider(argv: string[], deps: RuntimeApiDeps): Promise<number> {
const args = [...argv];
const name = args.shift()?.trim();
const wantsJson = takeFlag(args, "--json");
if (!name) throw new CliUsageError("provider name is required", USAGE);
const model = takeOption(args, "--model")?.trim();
const yes = takeFlag(args, "--yes");
rejectArgs(args, USAGE);
if (yes && model === undefined) throw new CliUsageError("--yes requires --model", USAGE);
if (model !== undefined) {
if (!model || model.length > 256 || /[\x00-\x1f\x7f-\x9f]/.test(model)) {
throw new CliUsageError("--model must contain 1..256 characters without control characters", USAGE);
}
return testCompletion(name, model, yes, wantsJson, deps);
}
const result = await runtimeRequest<Record<string, unknown>>(`/api/providers/test?name=${encodeURIComponent(name)}`, {
method: "POST",
}, deps);
if (result.applicable === false) {
printData(result, wantsJson, [
`${name}: not applicable`,
"Static catalog; no live model-discovery endpoint to test.",
]);
return 0;
}
const ok = result.ok === true;
printData(result, wantsJson, [
`${name}: ${ok ? "connected" : "failed"}`,
String(result.message ?? result.error ?? "No detail"),
`Latency: ${String(result.latencyMs ?? "?")} ms`,
]);
return ok ? 0 : 1;
}
async function quota(argv: string[], deps: RuntimeApiDeps): Promise<void> {
const args = [...argv];
const wantsJson = takeFlag(args, "--json");
const refresh = takeFlag(args, "--refresh");
rejectArgs(args, USAGE);
const result = await runtimeRequest<ProviderQuotasDto>(`/api/provider-quotas${refresh ? "?refresh=1" : ""}`, {}, deps);
// `summaryLines` is a depth-1 flattener: it renders a non-scalar array as "N item(s)", which
// collapsed the whole report to a count and made the command useless for its stated purpose
// (#2565). Render one line per report with the same formatter `ocx account refresh` uses.
const reports = Array.isArray(result?.reports) ? result.reports : [];
const lines = reports.length > 0
? reports.map(report => providerQuotaLine(report.provider, report))
: ["no quota reports available"];
printData(result, wantsJson, lines);
}
/**
* Recently detected quota resets, newest first.
*
* `accountTag` is deliberately NOT rendered: it is a salted hash that means nothing to a human
* reading a terminal, and printing it invites treating an opaque tag as an account identifier.
*/
function quotaResetLine(event: QuotaResetEventDto): string {
const when = typeof event.detectedAt === "number"
? new Date(event.detectedAt).toISOString()
: "unknown time";
const movement = typeof event.percentBefore === "number" && typeof event.percentAfter === "number"
? `${event.percentBefore}% -> ${event.percentAfter}%`
: "usage unknown";
const next = typeof event.resetAt === "number"
? `, next ${new Date(event.resetAt).toISOString()}`
: "";
return `${when} ${event.scope ?? "?"} ${event.window ?? "?"} ${event.kind ?? "?"}: ${movement}${next}`;
}
async function resets(argv: string[], deps: RuntimeApiDeps): Promise<void> {
const args = [...argv];
const wantsJson = takeFlag(args, "--json");
const limitRaw = takeOption(args, "--limit");
rejectArgs(args, USAGE);
if (limitRaw !== undefined && !/^\d+$/.test(limitRaw)) {
throw new CliUsageError("--limit must be a non-negative integer", USAGE);
}
const query = limitRaw === undefined ? "" : `?limit=${limitRaw}`;
const result = await runtimeRequest<QuotaResetsDto>(`/api/quota-resets${query}`, {}, deps);
const events = Array.isArray(result?.events) ? result.events : [];
// One line per event, NOT summaryLines: that helper is a depth-1 flattener and renders a
// non-scalar array as "N item(s)", which is what made `ocx provider quota` useless in #2565.
const lines = events.length > 0
? events.map(quotaResetLine)
// An empty list is ambiguous, so say which kind of empty it is. Without this an operator
// cannot tell "nothing has reset yet" from "I never turned this on".
: [result?.enabled === true
? "no resets detected yet"
: "quota-reset notifications are disabled (set quotaResetNotify.enabled)"];
printData(result, wantsJson, lines);
}
async function presets(argv: string[], deps: RuntimeApiDeps): Promise<void> {
const args = [...argv];
const wantsJson = takeFlag(args, "--json");
rejectArgs(args, USAGE);
const result = await runtimeRequest<{ providers?: unknown[] } | unknown[]>("/api/provider-presets", {}, deps);
const rows = Array.isArray(result) ? result : result.providers ?? [];
const pinned = pinSponsorRows(
rows,
row => {
const tier = (row as Record<string, unknown>)?.sponsor;
return tier === "main" || tier === "standard" ? tier : undefined;
},
row => String((row as Record<string, unknown>)?.label ?? (row as Record<string, unknown>)?.id ?? ""),
);
printData(result, wantsJson, pinned.map(row => {
const record = row as Record<string, unknown>;
const sponsor = record.sponsor ? ` (sponsor: ${String(record.sponsor)})` : "";
return `${String(record.id ?? record.name ?? "?")} ${String(record.label ?? record.adapter ?? "")}${sponsor}`.trimEnd();
}));
}
async function accountMode(argv: string[], deps: RuntimeApiDeps): Promise<void> {
const args = [...argv];
const mode = args.shift();
const wantsJson = takeFlag(args, "--json");
if (mode !== "pool" && mode !== "direct") throw new CliUsageError("mode must be pool or direct", USAGE);
rejectArgs(args, USAGE);
const result = await runtimeRequest("/api/providers?name=openai", {
method: "PATCH",
body: JSON.stringify({ codexAccountMode: mode }),
}, deps);
printData(result, wantsJson, [`OpenAI Codex account mode: ${mode}`]);
}
async function selected(argv: string[], deps: RuntimeApiDeps): Promise<void> {
const args = [...argv];
const name = args.shift()?.trim();
const wantsJson = takeFlag(args, "--json");
const set = csv(takeOption(args, "--set"));
const clear = takeFlag(args, "--clear");
if (!name) throw new CliUsageError("provider name is required", USAGE);
if (set !== undefined && clear) throw new CliUsageError("--set and --clear cannot be combined", USAGE);
rejectArgs(args, USAGE);
if (set === undefined && !clear) {
const result = await runtimeRequest<Record<string, unknown>>("/api/selected-models", {}, deps);
const selectedMap = (result.selected ?? {}) as Record<string, string[]>;
const availableMap = (result.available ?? {}) as Record<string, string[]>;
printData({ provider: name, selected: selectedMap[name] ?? [], available: availableMap[name] ?? [] }, wantsJson,
[`Selected models for ${name}: ${(selectedMap[name] ?? []).join(", ") || "all"}`]);
return;
}
const models = clear ? [] : (set ?? []);
const result = await runtimeRequest("/api/selected-models", {
method: "PUT",
body: JSON.stringify({ provider: name, models }),
}, deps);
printData(result, wantsJson, [`${name}: ${models.length ? models.join(", ") : "all models"}`]);
}
async function keychain(argv: string[], deps: RuntimeApiDeps): Promise<void> {
const args = [...argv];
const name = args.shift()?.trim();
const wantsJson = takeFlag(args, "--json");
const action = (args.shift() ?? "status").toLowerCase();
if (!name) throw new CliUsageError("provider name is required", USAGE);
if (!["status", "store", "restore"].includes(action)) throw new CliUsageError(`unknown keychain action ${action}`, USAGE);
rejectArgs(args, USAGE);
if (action === "status") {
const result = await runtimeRequest<Record<string, unknown>>(`/api/providers/keychain?name=${encodeURIComponent(name)}`, {}, deps);
printData(result, wantsJson, summaryLines(result));
return;
}
const result = await runtimeRequest<Record<string, unknown>>("/api/providers/keychain", {
method: "POST",
body: JSON.stringify({ name, action }),
}, deps);
printData(result, wantsJson, [action === "store"
? `${name}: API key moved to the OS keychain; config.json now holds a keychain: reference.`
: `${name}: API key restored to config.json; keychain entries removed.`]);
}
export async function handleProviderRuntimeCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
if (sub === "edit" || sub === "update") return runProviderAction(() => edit(argv, deps));
const handlers: Record<string, (args: string[], deps: RuntimeApiDeps) => Promise<number | void>> = {
test: testProvider,
quota,
resets,
presets,
"account-mode": accountMode,
selected,
keychain,
};
const handler = handlers[sub];
if (!handler) return null;
let outcome: number | void = 0;
const exit = await runCliAction(async () => { outcome = await handler(argv, deps); });
return exit || outcome || 0;
}
export const PROVIDER_RUNTIME_USAGE = USAGE;