UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,282 lines • 64.2 kB
import * as z from "zod/v4";
import { EXPORT_CLIENT_IDS } from "../../clients/client-ids";
import { accountAutoPausePolicySchema, accountPauseDetailsSchema } from "./account-auto-pause";
import { anthropicAccountPoolSchema } from "./anthropic-account-pool";
import { join } from "node:path";
import { isValidProviderName } from "../provider-name";
import {
  modelPinnedEffortsConfigError,
  pinnedReasoningEffortConfigError,
  modelDisplayNamesConfigError,
  autoReviewOverrideConfigError,
  autoReviewModelOverridesConfigError,
  autoReviewModelTargetConfigError,
  normalizeNonBlankStringArray,
  normalizeAutoReviewModelOverrides,
  modelCapabilitiesConfigError,
  providerInputModalitiesConfigError,
  contextTierRecordConfigError,
  mergeModelCapabilities,
} from "../provider-validation";
import { isValidCodexAccountNamespaceTarget } from "../../codex/account-namespace-match";
import { isCodexAccountPriorityKey } from "../../codex/account-priority";
import { isCodexAccountAutoSwitchThresholdKey, parseCodexAutoSwitchThreshold } from "../../codex/account-auto-switch";
import { parseAccountPriority } from "../../codex/pool-rotation";
import { credentialGroupIssues } from "../../routing/identity-domains";
import { providerDestinationConfigError } from "../../lib/destination-policy";
import { providerEgressConfigError } from "../../lib/provider-egress";
import { redactSecretString } from "../../lib/redact";
import {
  MODEL_ADAPTER_OVERRIDE_ALLOWED,
  pinnedWireAdapter,
  PROVIDER_WEB_SEARCH_BRIDGE_BACKENDS,
  THINKING_DISPLAY_VALUES,
  UPSTREAM_HTTP_VERSION_VALUES,
  type OcxProviderConfig,
  type OcxConfig,
  type FastWire,
  type ProviderCostOverlay,
} from "../../types";
import { fastWireDeclarationError } from "../../providers/fastwire";
import { getProviderRegistryEntry, providerMatchesRegistryTransport, providerModelWireDefault } from "../../providers/registry";
import { resolveOpenAiVirtualModel } from "../../providers/openai-virtual-models";
import { COST4_RATE_KEYS, isValidCost4Rate, isValidPromptLengthPricing, copyPromptLengthPricing } from "../../usage/user-cost-overlays";
import { MAX_COST4_RATE } from "../../usage/expected-prices";
import { isValidCreditPriceBound } from "../../usage/credit-billing";
import {
  DECLARABLE_HOSTED_TOOL_TYPES,
  declaredUnsupportedHostedTools,
  isHostedToolUnsupportedForModel,
} from "../../responses/hosted-tool-policy";
import { getConfigDir } from "../paths";
import { COMPACTION_TRIGGERS, validCompactionSourceModels } from "./compaction-triggers";

// The chatgptDesktop leaf lives in its own zod-only module so the `ocx chatgpt` command can explain
// a dropped block without loading this file's provider and account validators.
export { chatgptDesktopConfigIssue, chatgptDesktopSchema } from "./chatgpt-desktop";

/** One definition of "usable secret", shared by the schema and the warnings. */
export function isUsableApiKeySecret(value: unknown): value is string {
  return typeof value === "string" && value.length > 0 && value === value.trim();
}

export const compactionRoutingSchema = z.object({
  model: z.string().trim().min(1),
  sourceModels: z.array(z.string()).refine(validCompactionSourceModels,
    "sourceModels requires unique exact selectors or provider/* patterns").optional(),
  reasoningEffort: z.string().refine(value => pinnedReasoningEffortConfigError(value) === null).optional(),
  triggers: z.array(z.enum(COMPACTION_TRIGGERS)).nonempty()
    .refine(values => new Set(values).size === values.length, "triggers must not repeat a value")
    .optional(),
}).strict();

export const reasoningRetentionSchema = z.object({
  enabled: z.boolean().optional(),
  maxContextPercent: z.number().gt(0).max(100).optional(),
  maxTokens: z.number().int().positive().optional(),
}).strict();

/**
 * One phase of Codex's memory pipeline. A present phase must name a model: the GUI's "Off"
 * removes the phase instead of blanking it, so an empty entry would only ever come from a
 * hand-edited file, where failing the write is the honest answer.
 */
export const memoryModelSettingSchema = z.object({
  model: z.string().trim().min(1),
  reasoningEffort: z.string().refine(value => pinnedReasoningEffortConfigError(value) === null).optional(),
}).strict();

export const memoryModelsSchema = z.object({
  extract: memoryModelSettingSchema.optional(),
  consolidation: memoryModelSettingSchema.optional(),
}).strict();

/**
 * Bounds for the opt-in same-target 429 wait-and-retry policy. Single source of truth
 * shared by the config schema, the load-time sanitizer, and the management write
 * boundary. Strict, so an unknown key is rejected at every validation boundary instead
 * of being silently ignored (the load-time sanitizer still degrades unknown keys with a
 * warning before schema validation, so hand-edited configs keep loading).
 */
export const retryOn429PolicySchema = z.object({
  enabled: z.boolean().optional(),
  attempts: z.number().int().min(1).max(20).optional(),
  intervalMs: z.number().int().min(100).max(600_000).optional(),
  // The effective cap for a single wait is MAX_COOLDOWN_MS (10 min) in key-failover.ts;
  // larger configured values would be dead config.
  maxIntervalMs: z.number().int().min(100).max(600_000).optional(),
  respectRetryAfter: z.boolean().optional(),
}).strict();

/**
 * `transientRetryOn5xx` accepts only these keys. `attempts` is a TOTAL send budget shared by
 * both retry layers, so the ceiling is deliberately lower than `retryOn429`'s: 10 total sends
 * against an already-failing provider is already generous.
 */
export const transientRetryOn5xxPolicySchema = z.object({
  enabled: z.boolean().optional(),
  attempts: z.number().int().min(1).max(10).optional(),
}).strict();

/**
 * `retryOnReset` accepts only these keys. `replacements` counts DUPLICATE inferences the
 * operator is willing to risk for one logical request, so the ceiling is two rather than a
 * send budget: this is the one send the proxy otherwise refuses outright, and a third of them
 * says the connection, not the retry policy, is the problem.
 */
export const retryOnResetPolicySchema = z.object({
  enabled: z.boolean().optional(),
  replacements: z.number().int().min(1).max(2).optional(),
}).strict();

const requestPacingRuleSchema = z.object({
  // Keep the RPM-derived timer within the same one-hour bound as minIntervalMs.
  requestsPerMinute: z.number().min(1 / 60).max(60_000).optional(),
  minIntervalMs: z.number().int().min(1).max(3_600_000).optional(),
  maxConcurrentRequests: z.number().int().min(1).optional(),
}).strict().refine(value => value.requestsPerMinute !== undefined
  || value.minIntervalMs !== undefined
  || value.maxConcurrentRequests !== undefined, {
  message: "request pacing rules need requestsPerMinute, minIntervalMs, or maxConcurrentRequests",
});

const requestPacingSchema = z.object({
  enabled: z.boolean(),
  requestsPerMinute: z.number().min(1 / 60).max(60_000).optional(),
  minIntervalMs: z.number().int().min(1).max(3_600_000).optional(),
  maxConcurrentRequests: z.number().int().min(1).optional(),
  models: z.record(z.string().trim().min(1), requestPacingRuleSchema).optional(),
  keySelection: z.enum(["active", "round-robin"]).optional(),
  keys: requestPacingRuleSchema.optional(),
}).strict().refine(value => value.enabled === false
  || value.requestsPerMinute !== undefined
  || value.minIntervalMs !== undefined
  || value.maxConcurrentRequests !== undefined
  || value.keys !== undefined || value.keySelection === "round-robin"
  || (value.models !== undefined && Object.keys(value.models).length > 0), {
  message: "enabled request pacing needs a provider, model, or key rule, or round-robin selection",
});

/** Upper bounds for provider-scoped upstream budgets: the largest setTimeout delay, in ms. */
export const PROVIDER_CONNECT_TIMEOUT_MAX_MS = 2_147_483_647;
export const PROVIDER_STALL_TIMEOUT_MAX_SEC = 2_147_483;

/**
 * Validate provider-scoped `connectTimeoutMs` / `stallTimeoutSec` on a strict write. Absent is
 * valid (inherit the global value); otherwise each must be an integer from 0 (disabled for this
 * provider) to its maximum. Returns null when valid, else a human-readable error.
 */
export function providerTimeoutOverrideConfigError(provider: Record<string, unknown>): string | null {
  for (const [field, max] of [
    ["connectTimeoutMs", PROVIDER_CONNECT_TIMEOUT_MAX_MS],
    ["stallTimeoutSec", PROVIDER_STALL_TIMEOUT_MAX_SEC],
  ] as const) {
    const value = provider[field];
    if (value === undefined) continue;
    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > max) {
      return `${field} must be an integer from 0 to ${max}`;
    }
  }
  return null;
}

export function requestPacingConfigError(value: unknown): string | null {
  if (value === undefined) return null;
  const parsed = requestPacingSchema.safeParse(value);
  if (parsed.success) return null;
  return "requestPacing must contain enabled and a valid requestsPerMinute/minIntervalMs/maxConcurrentRequests provider rule or model overrides";
}

/**
 * Bounds for the opt-in passthrough web-search bridge (`providers.<name>.webSearchBridge`,
 * #3761). Strict for the same reason `retryOn429` is: a misspelled key here would silently
 * leave the bridge disarmed while the operator believes they enabled it.
 *
 * `endpoint` names the destination that receives this provider's API key, so it gets the same
 * literal destination assessment `baseUrl` gets (#4519) — see `providerWebSearchBridgeConfigError`
 * below. This schema itself still only shape-checks: it is `.catch(undefined)` at the provider
 * row, and a hand-edited config file never reaches the error function at all. The authorization
 * boundary is therefore `resolveOllamaWebSearchEndpoint`, which runs the same assessment and is
 * the only reader of this field in the tree; config validation is where an operator is told why,
 * not what makes the value safe.
 */
const providerWebSearchBridgeSchema = z.object({
  enabled: z.boolean().optional(),
  backend: z.enum(PROVIDER_WEB_SEARCH_BRIDGE_BACKENDS).optional(),
  maxSearches: z.number().int().min(1).max(10).optional(),
  timeoutMs: z.number().int().min(1_000).max(600_000).optional(),
  endpoint: z.string().min(1).optional(),
}).strict();

export function providerWebSearchBridgeConfigError(
  value: unknown,
  providerName: string,
  provider: Pick<OcxProviderConfig, "allowPrivateNetwork">,
): string | null {
  if (value === undefined) return null;
  if (!value || typeof value !== "object" || Array.isArray(value)) {
    return "webSearchBridge must be a plain object";
  }
  const parsed = providerWebSearchBridgeSchema.safeParse(value);
  if (!parsed.success) {
    return "webSearchBridge accepts only enabled (boolean), backend "
      + `(${PROVIDER_WEB_SEARCH_BRIDGE_BACKENDS.join("|")}), maxSearches (1..10), `
      + "timeoutMs (1000..600000), and endpoint (absolute http(s) URL)";
  }
  const endpoint = parsed.data.endpoint;
  if (endpoint !== undefined) {
    let url: URL;
    try {
      url = new URL(endpoint);
    } catch {
      return "webSearchBridge.endpoint must be an absolute http(s) URL";
    }
    if (url.protocol !== "https:" && url.protocol !== "http:") {
      return "webSearchBridge.endpoint must be an absolute http(s) URL";
    }
    // Same classifier baseUrl uses, so a metadata address is refused outright and loopback or
    // private space needs the provider's allowPrivateNetwork opt-in (or a registry entry that is
    // local by definition, which is what keeps a self-hosted Ollama working). Literal-only and
    // synchronous, exactly as at the baseUrl boundary: no DNS is resolved here.
    const destinationError = providerDestinationConfigError(providerName, {
      baseUrl: endpoint,
      allowPrivateNetwork: provider.allowPrivateNetwork,
    });
    if (destinationError) {
      return destinationError.replace(/^baseUrl/, "webSearchBridge.endpoint");
    }
  }
  return null;
}

const fastWireSchema = z.object({
  kind: z.string(),
  canonicalToWire: z.record(z.string().trim(), z.string().trim()),
  foreignCallerTiers: z.string(),
  betas: z.array(z.string().trim()).optional(),
}).strict().superRefine((fastWire, ctx) => {
  const error = fastWireDeclarationError({ fastWire });
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(fastWire => fastWire as FastWire);

const modelDisplayNamesSchema = z.unknown().superRefine((value, ctx) => {
  const error = modelDisplayNamesConfigError(value);
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(value => {
  const labels = Object.create(null) as Record<string, string>;
  for (const [modelId, displayName] of Object.entries(value as Record<string, string>)) {
    labels[modelId] = displayName;
  }
  return labels;
});

const pinnedReasoningEffortSchema = z.unknown().superRefine((value, ctx) => {
  const error = pinnedReasoningEffortConfigError(value);
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(value => value as string);

export const modelPinnedEffortsSchema = z.unknown().superRefine((value, ctx) => {
  const error = modelPinnedEffortsConfigError(value);
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(value => Object.fromEntries(
  Object.entries(value as Record<string, string>).map(([key, effort]) => [key.trim(), effort]),
));

const autoReviewModelSchema = z.unknown().superRefine((value, ctx) => {
  const error = autoReviewModelTargetConfigError(value, "autoReviewModel", true);
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(value => {
  if (typeof value !== "string") return undefined;
  const trimmed = value.trim();
  return trimmed ? trimmed : undefined;
});

const autoReviewModelOverridesSchema = z.unknown().superRefine((value, ctx) => {
  const error = autoReviewModelOverridesConfigError(value, "autoReviewModelOverrides", true);
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(value => normalizeAutoReviewModelOverrides(value));

/** Global auto-review override block; a malformed hand edit is stripped by load degradation. */
export const autoReviewOverrideSchema = z.unknown().superRefine((value, ctx) => {
  const error = autoReviewOverrideConfigError(value, "autoReviewOverride");
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(value => value as NonNullable<OcxConfig["autoReviewOverride"]>);

const modelCapabilitiesSchema = z.unknown().superRefine((value, ctx) => {
  const error = modelCapabilitiesConfigError(value);
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(value => mergeModelCapabilities(undefined, value));

/**
 * Per-provider egress fields, validated by the resolver the transports themselves use.
 *
 * Calling `providerEgressConfigError` rather than restating the accepted forms keeps one
 * definition of a usable value: a proxy the config loader admits is one the transport can
 * carry, and a value rejected here is rejected at request time for the identical reason.
 * Each field is checked on its own because neither depends on the other's value to be
 * well-formed; how they combine is decided per request against the destination.
 */
const providerProxySchema = z.unknown().superRefine((value, ctx) => {
  const error = providerEgressConfigError({ proxy: value as string | null | undefined });
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(value => value as string | null | undefined);

const providerNoProxySchema = z.unknown().superRefine((value, ctx) => {
  const error = providerEgressConfigError({ noProxy: value as string | string[] | undefined });
  if (error) ctx.addIssue({ code: "custom", message: error });
}).transform(value => value as string | string[] | undefined);

/**
 * A provider's hosted-tool denial list, validated against a closed vocabulary rather than
 * accepted as free strings. The provider schema ends in `.passthrough()`, so a misspelled
 * `web_serch` would otherwise be accepted, persisted, and strip nothing -- leaving the
 * operator with the upstream 400 the field was set to prevent, and no message saying why
 * (the `codexToolMode` lesson, #2106).
 */
function hostedToolDenialSchema(field: string) {
  return z.array(z.string().min(1))
    .transform(normalizeNonBlankStringArray)
    .refine(
      tools => tools.every(tool => DECLARABLE_HOSTED_TOOL_TYPES.has(tool)),
      { message: `${field} accepts only hosted tool types: ${[...DECLARABLE_HOSTED_TOOL_TYPES].join(", ")}` },
    )
    .optional();
}

/**
 * Zod schema for one provider entry: known fields are validated strictly while unknown
 * fields pass through (preserved for runtime extensions).
 */
export const providerConfigSchema = z.object({
  accountAutoPause: accountAutoPausePolicySchema.optional(),
  apiKeyPool: z.array(z.object({ id: z.string(), key: z.string(), label: z.string().optional(), addedAt: z.number().optional(), disabled: z.boolean().optional(), pauseRevision: z.string().optional(), pauseDetails: accountPauseDetailsSchema.optional() }).passthrough()).optional(),
  anthropicAccountPool: anthropicAccountPoolSchema,
  anthropicImageContextRecovery: z.boolean().optional(),
  // Raw diagnostics/writes reject malformed provenance; tolerant loads preserve the custom row.
  anthropicOAuthInstance: z.literal("anthropic2").optional().catch(undefined),
  modelCapabilities: modelCapabilitiesSchema.optional(),
  inputModalities: z.unknown().superRefine((value, ctx) => {
    const error = providerInputModalitiesConfigError(value);
    if (error) ctx.addIssue({ code: "custom", message: error });
  }).optional().transform(value => value as OcxProviderConfig["inputModalities"]),
  modelContextTiers: z.unknown().superRefine((value, ctx) => {
    const error = contextTierRecordConfigError(value);
    if (error) ctx.addIssue({ code: "custom", message: error });
  }).optional().transform(value => value as OcxProviderConfig["modelContextTiers"]),
  pinnedReasoningEffort: pinnedReasoningEffortSchema.optional(),
  modelPinnedReasoningEfforts: modelPinnedEffortsSchema.optional(),
  // Validated rather than left to passthrough: an unrecognized strategy would otherwise
  // load silently and then be ignored at selection time, which reads as a broken feature
  // rather than a rejected setting.
  apiKeyPoolStrategy: z.enum(["round-robin", "fill-first", "quota"]).optional(),
  // Strict writes reject invalid modes; load degradation removes invalid hand edits.
  cacheAffinity: z.enum(["auto", "session", "turn", "off"]).optional(),
  autoReviewModel: autoReviewModelSchema.optional(),
  autoReviewModelOverrides: autoReviewModelOverridesSchema.optional(),
  adapter: z.string().min(1),
  baseUrl: z.string().min(1),
  tlsProfile: z.literal("antigravity-browser").optional(),
  alias: z.string().optional(),
  modelAliases: z.record(z.string(), z.string()).optional(),
  // Grammar is checked by sanitizeAliasesForLoad and the alias-template route (#7705).
  aliasTemplate: z.string().optional(),
  modelDisplayNames: modelDisplayNamesSchema.optional(),
  defaultAliases: z.boolean().optional(),
  initialModelSelection: z.object({
    version: z.literal(1),
    registrationId: z.uuid(),
    status: z.enum(["pending", "ready", "all-off"]),
    modelCount: z.number().int().nonnegative().optional(),
  }).optional().catch(undefined),
  requestPacing: requestPacingSchema.optional().catch(undefined),
  // Provider-scoped header/body budgets; a malformed hand edit degrades to "inherit the global".
  connectTimeoutMs: z.number().int().min(0).max(PROVIDER_CONNECT_TIMEOUT_MAX_MS).optional().catch(undefined),
  stallTimeoutSec: z.number().int().min(0).max(PROVIDER_STALL_TIMEOUT_MAX_SEC).optional().catch(undefined),
  mcpMaxTools: z.number().int().positive().optional(),
  mcpMaxSchemaBytes: z.number().int().positive().optional(),
  mcpMaxResultBytes: z.number().int().positive().optional(),
  apiKeyTransport: z.enum(["x-api-key", "bearer"]).optional(),
  anthropicOAuthUserInstructions: z.boolean().optional(),
  responsesPath: z.string().min(1).optional(),
  chatCompletionsPath: z.string().min(1).optional(),
  statelessResponses: z.boolean().optional(),
  requiresAdjacentResponsesToolResults: z.boolean().optional(),
  requiresPairedResponsesToolResults: z.boolean().optional(),
  annotateEmptyToolOutputs: z.boolean().optional(),
  foldDeveloperRoleToSystem: z.boolean().optional(),
  singleLeadingSystemMessage: z.boolean().optional(),
  fastWire: fastWireSchema.nullable().optional(),
  responseTierAuthoritative: z.boolean().optional(),
  fastEnabled: z.boolean().optional(),
  supportsServiceTier: z.boolean().optional(),
  inferContextWindow: z.boolean().optional(),
  modelSupportsServiceTier: z.record(z.string().min(1), z.boolean()).optional(),
  modelSuppressSyntheticMax: z.record(z.string().min(1), z.boolean()).optional(),
  // Validated against a closed vocabulary here as well as at the write boundaries, so a
  // hand-edited typo cannot load silently and leave the operator with the built-in display (#8363).
  thinkingDisplay: z.enum(THINKING_DISPLAY_VALUES).optional(),
  modelThinkingDisplay: z.record(z.string().min(1), z.enum(THINKING_DISPLAY_VALUES)).optional(),
  promoteAdditionalTools: z.boolean().optional(),
  preserveResponsesReasoningContent: z.boolean().optional(),
  preserveResponsesInputItemIds: z.boolean().optional(),
  preserveResponsesMessageMetadata: z.boolean().optional(),
  projectResponsesLiteHostedSearchHistory: z.boolean().optional(),
  dropResponsesReasoningItems: z.boolean().optional(),
  arkKimiResponsesModels: z.array(z.string().min(1)).optional(),
  modelReasoningEffortsAuthoritative: z.boolean().optional(),
  decodesNativeCompactionBlobs: z.boolean().optional(),
  supportsNativeCompactionTrigger: z.boolean().optional(),
  supportsNativeCompactEndpoint: z.boolean().optional(),
  allowEncryptedV2AgentTasks: z.boolean().optional(),
  allowPrivateNetwork: z.boolean().optional(),
  // Per-provider egress (#2894): absent inherits the global proxy decision, "direct"/null
  // refuses it, and an http(s) or socks5 URL replaces it for this provider only.
  proxy: providerProxySchema.optional(),
  noProxy: providerNoProxySchema.optional(),
  // The management API accepts `null` as "clear this", so a config written before the POST
  // canonicalization below can hold one on disk. Rejecting it here would send the operator
  // through invalid-config recovery for a value the API told them was fine.
  upstreamHttpVersion: z.enum(UPSTREAM_HTTP_VERSION_VALUES)
    .nullish()
    .transform(value => value ?? undefined),
  // Opt-in upstream Responses WebSocket for OpenAI-compatible providers, honored only
  // for the first-party api.openai.com/v1 upstream; other custom endpoints stay on
  // bounded HTTP/SSE. On the canonical ChatGPT `openai` provider the same field selects
  // the transport: omitted keeps the upstream WebSocket on eligible turns, explicit
  // `false` sends streaming turns over HTTP/SSE, and provider management rejects `true`.
  upstreamWebsocket: z.boolean().optional(),
  directGeminiWireRenames: z.boolean().optional(),
  googleToolSchemaPolicy: z.enum(["compatible", "reject-lossy"]).optional(),
  noStructuredOutputModels: z.array(z.string().min(1))
    .transform(normalizeNonBlankStringArray)
    .optional(),
  noJsonSchemaModels: z.array(z.string().min(1))
    .transform(normalizeNonBlankStringArray)
    .optional(),
  retainModels: z.array(z.string().min(1))
    .transform(normalizeNonBlankStringArray)
    .optional(),
  // Provider-level discovery compatibility (#7910), unrelated to the top-level persisted
  // `modelDiscovery` state. Degrades to "absent" (strict discovery) like the other default-off
  // opt-ins; the management write boundary still rejects a malformed block loudly.
  modelDiscovery: z.object({ skipInvalidRows: z.boolean().optional() }).strict().optional().catch(undefined),
  omitReasoningEffortWithToolsModels: z.array(z.string().min(1))
    .transform(normalizeNonBlankStringArray)
    .optional(),
  unsupportedHostedTools: hostedToolDenialSchema("unsupportedHostedTools"),
  // Same closed vocabulary; applied only when the request also declares client tools (#8204).
  unsupportedHostedToolsWithClientTools: hostedToolDenialSchema("unsupportedHostedToolsWithClientTools"),
  retryOn429: retryOn429PolicySchema.optional(),
  transientRetryOn5xx: transientRetryOn5xxPolicySchema.optional(),
  // Degrades to "absent" like `webSearchBridge`: a malformed hand edit of an opt-in feature
  // that is off by default must not send the operator through invalid-config recovery. The
  // management write boundary still rejects it loudly (`retryOnResetPolicyConfigError`).
  retryOnReset: retryOnResetPolicySchema.optional().catch(undefined),
  codexAccountMode: z.enum(["pool", "direct"]).optional(),
  // Validated rather than passed through: this schema ends in `.passthrough()`, so an
  // undeclared key survives verbatim. A misspelled `codexToolMode` therefore used to be
  // accepted, persisted, and then silently resolved to the `code_mode_only` default — the
  // operator asked for shell mode, got code mode, and was told nothing (#2106).
  codexToolMode: z.enum(["code_mode_only", "shell"]).optional(),
  projectContext: z.enum(["off", "on"]).optional(),
  responsesItemIdRepair: z.object({
    message: z.array(z.string().min(1)).optional(),
    reasoning: z.array(z.string().min(1)).optional(),
    repairMissingTerminalIds: z.boolean().optional(),
    repairInvalidIds: z.boolean().optional(),
  }).strict().optional(),
  responsesSnapshotRepair: z.boolean().optional(),
  messagePhaseInference: z.boolean().optional(),
  estimateMissingUsage: z.boolean().optional(),
  hideRawReasoning: z.boolean().optional(),
  rawReasoningAsSummary: z.boolean().optional(),
  forwardAdvisorTool: z.boolean().optional(),
  perMessageEffort: z.boolean().optional(),
  // Invalid blocks degrade to "absent" rather than failing the whole config load: an unusable
  // bridge block must never send an operator through invalid-config recovery for an opt-in
  // feature that is off by default. The management write boundary still rejects it loudly.
  webSearchBridge: providerWebSearchBridgeSchema.optional().catch(undefined),
  xaiResponsesXSearch: z.boolean().optional(),
  xaiResponsesDefaultVersion: z.number().int().positive().optional().catch(undefined),
  zaiResponsesDefaultVersion: z.number().int().positive().optional().catch(undefined),
}).passthrough().superRefine((provider, ctx) => {
  if (provider.projectContext !== undefined && provider.adapter !== "command-code") {
    ctx.addIssue({ code: "custom", path: ["projectContext"], message: "projectContext is supported only by the command-code adapter" });
  }
});


export { providerRelativeSendPathConfigError } from "../provider-relative-send-path";

/**
 * A credit price is a finite number of USD per provider credit, zero or more, and small enough
 * that `credits x price` stays representable for any admissible credit count. Bounding the price
 * alone is not enough — see `src/usage/credit-billing.ts` — so the bound is chosen to keep the
 * product inside the safe range rather than merely finite.
 */
export function isValidCreditPriceUsd(value: unknown): value is number {
  return isValidCreditPriceBound(value);
}

/**
 * Validate `providers.<name>.modelCosts`: a plain object keyed by exact model
 * id, each value four USD-per-1M-token rates and an optional prompt-length policy.
 * Returns null when valid/absent, else a human-readable error.
 */
export function providerModelCostsConfigError(value: unknown, field = "modelCosts"): string | null {
  if (value === undefined) return null;
  if (!value || typeof value !== "object" || Array.isArray(value)) {
    return `${field} must be a plain object keyed by model id`;
  }
  for (const [modelId, entry] of Object.entries(value)) {
    if (!modelId.trim()) return `${field} keys must be nonblank model ids`;
    // Redact secret-shaped model ids and JSON-escape control characters so a
    // malformed write cannot echo a pasted key/secret back through the
    // management API response.
    const safeModelId = JSON.stringify(redactSecretString(modelId));
    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
      return `${field}.${safeModelId} must be an object with input, output, cacheRead, and cacheWrite (USD per 1M tokens)`;
    }
    const rates = entry as Record<string, unknown>;
    for (const key of COST4_RATE_KEYS) {
      const rate = rates[key];
      if (!Object.hasOwn(rates, key) || !isValidCost4Rate(rate)) {
        return `${field}.${safeModelId}.${key} must be a non-negative finite number at most ${MAX_COST4_RATE} (USD per 1M tokens)`;
      }
    }
    if (Object.hasOwn(rates, "promptLengthPricing") && !isValidPromptLengthPricing(rates.promptLengthPricing)) {
      return `${field}.${safeModelId}.promptLengthPricing must be automatic, flat, or a complete custom policy with a positive safe-integer thresholdTokens, gt/gte comparison, and four valid rates`;
    }
    // Reject unknown fields: a misplaced apiKey/apiKeyPool under a cost row
    // would otherwise be persisted and echoed verbatim by display paths that
    // mask only top-level provider secrets.
    const extraKeys = Object.keys(rates)
      .filter((key) => key !== "promptLengthPricing" && !(COST4_RATE_KEYS as readonly string[]).includes(key));
    if (extraKeys.length > 0) {
      return `${field}.${safeModelId} has unexpected fields ${JSON.stringify(extraKeys.map(redactSecretString).join(", "))} — only input, output, cacheRead, cacheWrite, and promptLengthPricing are allowed (USD per 1M tokens)`;
    }
  }
  return null;
}

/**
 * Serialize `providers.<name>.modelCosts` for display: copy the four validated
 * rates and complete validated policy and DROP secret-shaped model ids, so a pasted
 * API key in a key position cannot be echoed back by CLI/DTO display paths.
 * The result uses a null prototype so "__proto__" remains an own row.
 */
export function sanitizeModelCostsForDisplay(costs: unknown): Record<string, ProviderCostOverlay> | undefined {
  if (!costs || typeof costs !== "object" || Array.isArray(costs)) return undefined;
  const out = Object.create(null) as Record<string, ProviderCostOverlay>;
  for (const [modelId, entry] of Object.entries(costs)) {
    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
    const rates = entry as Record<string, unknown>;
    if (Object.hasOwn(rates, "promptLengthPricing") && !isValidPromptLengthPricing(rates.promptLengthPricing)) continue;
    const input = rates.input;
    const output = rates.output;
    const cacheRead = rates.cacheRead;
    const cacheWrite = rates.cacheWrite;
    if (
      isValidCost4Rate(input)
      && isValidCost4Rate(output)
      && isValidCost4Rate(cacheRead)
      && isValidCost4Rate(cacheWrite)
    ) {
      // Secret-shaped ids are DROPPED rather than mapped to "[REDACTED]" so
      // distinct rows cannot collapse into one placeholder key.
      if (redactSecretString(modelId) !== modelId) continue;
      const policy = isValidPromptLengthPricing(rates.promptLengthPricing)
        ? copyPromptLengthPricing(rates.promptLengthPricing) : undefined;
      out[modelId] = { input, output, cacheRead, cacheWrite,
        ...(policy ? { promptLengthPricing: policy } : {}) };
    }
  }
  return Object.keys(out).length > 0 ? out : undefined;
}

const SUPPORTED_PREFERRED_HOSTED_TOOLS = new Set(["image_generation"]);

export function modelPreferHostedToolsConfigError(
  value: unknown,
  field: string,
  providerName: string,
  provider: {
    adapter?: unknown;
    authMode?: unknown;
    modelAdapters?: unknown;
    baseUrl?: unknown;
    unsupportedHostedTools?: unknown;
    unsupportedHostedToolsWithClientTools?: unknown;
  },
): string | null {
  if (value === undefined) return null;
  if (!value || typeof value !== "object" || Array.isArray(value)) return `${field} must be a plain object`;
  const prototype = Object.getPrototypeOf(value);
  if (prototype !== Object.prototype && prototype !== null) return `${field} must be a plain object with own properties`;
  const entries = Object.entries(value);
  const registry = getProviderRegistryEntry(providerName);
  // A provider that denies a hosted tool cannot also prefer it. Both keys are
  // provider-owned capability statements about the same tool, and the denial wins at
  // request time, so accepting the pair would silently ignore the preference.
  const declaredUnsupported = declaredUnsupportedHostedTools(
    provider as { unsupportedHostedTools?: readonly string[] },
  );
  // The conditional list (#8204) denies the same tool whenever client tools travel with it,
  // which is every Codex turn, so it cancels a preference just as surely.
  const declaredWithClientTools = declaredUnsupportedHostedTools(
    provider as { unsupportedHostedTools?: readonly string[]; unsupportedHostedToolsWithClientTools?: readonly string[] },
    true,
  );
  // Effective transport: a `preserveCustomDestination` registry row reused under a
  // different endpoint keeps its own adapter AND its own auth at runtime, because
  // `routedProviderConfig()` honors `providerMatchesRegistryTransport()`. Both the
  // wire check below and the forward-auth check here have to start from the same
  // decision, or validation accepts a preference the adapter never applies —
  // `preferConfiguredHostedTools()` runs only on the non-forward branch.
  const registryTransportMatches = typeof provider.baseUrl === "string"
    && providerMatchesRegistryTransport(providerName, {
      baseUrl: provider.baseUrl,
      adapter: provider.adapter as OcxProviderConfig["adapter"],
      ...(typeof provider.authMode === "string" ? { authMode: provider.authMode as OcxProviderConfig["authMode"] } : {}),
    });
  const effectiveForwardAuth = registryTransportMatches
    ? registry?.authKind === "forward"
    : provider.authMode === "forward";
  if (entries.length > 0 && effectiveForwardAuth) {
    return `${field} is not supported on forward-auth Responses providers`;
  }
  const requestedWireFor = (modelId: string): unknown => provider.modelAdapters
    && typeof provider.modelAdapters === "object"
    && !Array.isArray(provider.modelAdapters)
    ? (provider.modelAdapters as Record<string, unknown>)[modelId]
    : undefined;
  const resolveEffectiveWire = (modelId: string, currentWire: unknown): unknown => {
    const pinned = pinnedWireAdapter(providerName, modelId, provider);
    if (pinned) return pinned;
    const requestedWire = requestedWireFor(modelId);
    if (typeof requestedWire === "string" && MODEL_ADAPTER_OVERRIDE_ALLOWED.has(requestedWire)) {
      return requestedWire;
    }
    // No explicit override: fall back to the registry's per-model wire default before
    // the provider-wide adapter, because that is the order `resolveModelAdapter()`
    // uses at request time (src/server/adapter-resolve.ts:38-48). Skipping it rejected
    // preferences the runtime would have honored — DeepSeek routes `deepseek-v4-flash`
    // over native Responses for a Responses inbound while the provider-wide wire stays
    // openai-chat. Hosted-tool preferences only apply to Responses traffic, so the
    // inbound to ask about is "responses".
    const registryDefault = typeof currentWire === "string" && typeof provider.baseUrl === "string"
      ? providerModelWireDefault(
        providerName,
        {
          baseUrl: provider.baseUrl,
          adapter: currentWire,
          ...(typeof provider.authMode === "string" ? { authMode: provider.authMode as OcxProviderConfig["authMode"] } : {}),
        },
        modelId,
        MODEL_ADAPTER_OVERRIDE_ALLOWED,
        "responses",
      )
      : undefined;
    return registryDefault ?? currentWire;
  };
  for (const [key, entry] of entries) {
    if (!key.trim()) return `${field} keys must be nonblank model ids`;
    if (!Array.isArray(entry)) return `${field}.${key} must be an array`;
    if (entry.length === 0) return `${field}.${key} must include image_generation`;
    for (const tool of entry) {
      if (typeof tool !== "string" || !SUPPORTED_PREFERRED_HOSTED_TOOLS.has(tool)) {
        return `${field}.${key} supports only image_generation`;
      }
      if (declaredUnsupported.has(tool)) {
        return `${field}.${key} cannot prefer ${tool}: unsupportedHostedTools declares it unsupported`;
      }
      if (declaredWithClientTools.has(tool)) {
        return `${field}.${key} cannot prefer ${tool}: unsupportedHostedToolsWithClientTools declares it unsupported`;
      }
      if (isHostedToolUnsupportedForModel(key, tool)) {
        return `${field}.${key} cannot prefer ${tool}: the model does not support it`;
      }
    }
    // Same `registryTransportMatches` decision the forward-auth check above uses:
    // start from the registry adapter only when this config still points at the
    // registry's documented transport.
    const baseWire = registryTransportMatches ? registry?.adapter ?? provider.adapter : provider.adapter;
    let effectiveWire = resolveEffectiveWire(key, baseWire);
    const virtualWireModel = resolveOpenAiVirtualModel(providerName, key)?.wireModelId;
    if (virtualWireModel && virtualWireModel !== key) {
      effectiveWire = resolveEffectiveWire(virtualWireModel, effectiveWire);
    }
    if (effectiveWire !== "openai-responses") {
      return `${field}.${key} requires the openai-responses wire`;
    }
  }
  return null;
}

const CODEX_ACCOUNT_NAMESPACES_RECORD_ERROR =
  "codexAccountNamespaces must be a plain object mapping account selectors to Codex account ids";
const CODEX_ACCOUNT_NAMESPACE_KEY_ERROR =
  "account selectors must use 1-64 letters, numbers, dots, underscores, or hyphens and cannot be reserved JavaScript object keys";
const CODEX_ACCOUNT_NAMESPACE_TARGET_ERROR =
  "account selector targets must be @main or valid Codex pool-account ids";
export const CODEX_ACCOUNT_NAMESPACE_ACCOUNT_ID_COLLISION_ERROR =
  "account selectors must not collide with configured Codex pool-account ids or account selector targets";

export function configuredCodexPoolAccountIds(value: unknown): Set<string> {
  const accountIds = new Set<string>();
  if (!Array.isArray(value)) return accountIds;
  for (const account of value) {
    if (!account || typeof account !== "object" || Array.isArray(account)) continue;
    const { id, isMain } = account as { id?: unknown; isMain?: unknown };
    if (typeof id === "string" && isMain !== true) accountIds.add(id);
  }
  return accountIds;
}

export const codexAccountNamespacesSchema = z.custom<Record<string, unknown>>(
  (value): value is Record<string, unknown> => !!value
    && typeof value === "object"
    && !Array.isArray(value)
    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null),
  { error: CODEX_ACCOUNT_NAMESPACES_RECORD_ERROR },
).superRefine((accountNamespaces, ctx) => {
  // Inspect raw own entries before z.record parses them; Zod omits __proto__ record keys.
  for (const [namespace, accountId] of Object.entries(accountNamespaces)) {
    if (!isValidProviderName(namespace)) {
      ctx.addIssue({
        code: "custom",
        path: [namespace],
        message: CODEX_ACCOUNT_NAMESPACE_KEY_ERROR,
      });
    }
    if (!isValidCodexAccountNamespaceTarget(accountId)) {
      ctx.addIssue({
        code: "custom",
        path: [namespace],
        message: CODEX_ACCOUNT_NAMESPACE_TARGET_ERROR,
      });
    }
  }
}).pipe(z.record(z.string(), z.string()));

const CODEX_ACCOUNT_PRIORITIES_RECORD_ERROR =
  "codexAccountPriorities must be a plain object mapping Codex account ids to selection-order integers";
const CODEX_ACCOUNT_PRIORITY_KEY_ERROR =
  "selection-order keys must be a Codex pool-account id or the main Codex account and cannot be reserved JavaScript object keys";
const CODEX_ACCOUNT_PRIORITY_VALUE_ERROR =
  "selection order must be an integer between -100 and 100";

export const CODEX_ACCOUNT_PIN_PATTERN = /^[a-zA-Z0-9._-]{1,64}$/;

export const codexAccountPrioritiesSchema = z.custom<Record<string, unknown>>(
  (value): value is Record<string, unknown> => !!value
    && typeof value === "object"
    && !Array.isArray(value)
    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null),
  { error: CODEX_ACCOUNT_PRIORITIES_RECORD_ERROR },
).superRefine((priorities, ctx) => {
  // Inspect raw own entries before z.record parses them; Zod omits __proto__ record keys.
  for (const [accountId, priority] of Object.entries(priorities)) {
    if (!isCodexAccountPriorityKey(accountId)) {
      ctx.addIssue({ code: "custom", path: [accountId], message: CODEX_ACCOUNT_PRIORITY_KEY_ERROR });
    }
    if (parseAccountPriority(priority) === null) {
      ctx.addIssue({ code: "custom", path: [accountId], message: CODEX_ACCOUNT_PRIORITY_VALUE_ERROR });
    }
  }
}).pipe(z.record(z.string(), z.number().int()));

const codexQuotaAutoRefreshEntrySchema = z.object({
  fiveHour: z.boolean().optional(),
  weekly: z.boolean().optional(),
  lastFiveHourResetAt: z.number().finite().nonnegative().optional(),
  lastWeeklyResetAt: z.number().finite().nonnegative().optional(),
  nextFiveHourResetAt: z.number().finite().nonnegative().optional(),
  nextWeeklyResetAt: z.number().finite().nonnegative().optional(),
}).strict();
const CODEX_QUOTA_AUTO_REFRESH_KEY_ERROR =
  "quota auto-refresh keys must be a Codex pool-account id or the main Codex account and cannot be reserved JavaScript object keys";

const CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLDS_RECORD_ERROR =
  "codexAccountAutoSwitchThresholds must be a plain object mapping Codex account ids to usage thresholds";
const CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLD_KEY_ERROR =
  "usage-threshold keys must be a Codex pool-account id or the main Codex account and cannot be reserved JavaScript object keys";
const CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLD_VALUE_ERROR =
  "account usage threshold must be an integer between 0 and 100";

export const codexAccountAutoSwitchThresholdsSchema = z.custom<Record<string, unknown>>(
  (value): value is Record<string, unknown> => !!value
    && typeof value === "object"
    && !Array.isArray(value)
    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null),
  { error: CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLDS_RECORD_ERROR },
).superRefine((thresholds, ctx) => {
  for (const [accountId, threshold] of Object.entries(thresholds)) {
    if (!isCodexAccountAutoSwitchThresholdKey(accountId)) {
      ctx.addIssue({
        code: "custom",
        path: [accountId],
        message: CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLD_KEY_ERROR,
      });
    }
    if (parseCodexAutoSwitchThreshold(threshold) === null) {
      ctx.addIssue({
        code: "custom",
        path: [accountId],
        message: CODEX_ACCOUNT_AUTO_SWITCH_THRESHOLD_VALUE_ERROR,
      });
    }
  }
}).pipe(z.record(z.string(), z.number().int()));

/** Load only: retain valid overrides from a hand-edited map; writes use the strict schema above. */
export function salvageCodexAccountAutoSwitchThresholds(value: unknown): Record<string, number> | undefined {
  const parsed = codexAccountAutoSwitchThresholdsSchema.safeParse(value);
  if (parsed.success) return parsed.data;
  if (!value || typeof value !== "object" || Array.isArray(value)
    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return undefined;
  const valid: Record<string, number> = Object.create(null);
  for (const [accountId, threshold] of Object.entries(value)) {
    const parsedThreshold = parseCodexAutoSwitchThreshold(threshold);
    if (isCodexAccountAutoSwitchThresholdKey(accountId) && parsedThreshold !== null) {
      valid[accountId] = parsedThreshold;
    }
  }
  return Object.keys(valid).length ? valid : undefined;
}

export const codexQuotaAutoRefreshSchema = z.custom<Record<string, unknown>>(
  (value): value is Record<string, unknown> => !!value
    && typeof value === "object"
    && !Array.isArray(value)
    && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null),
  { error: "codexQuotaAutoRefresh must be a plain object" },
).superRefine((settings, ctx) => {
  // Inspect own entries before z.record parses them; Zod omits __proto__ record keys.
  for (const [accountId, setting] of Object.entries(settings)) {
    if (!isCodexAccountPriorityKey(accountId)) {
      ctx.addIssue({ code: "custom", path: [accountId], message: CODEX_QUOTA_AUTO_REFRESH_KEY_ERROR });
    }
    const parsed = codexQuotaAutoRefreshEntrySchema.safeParse(setting);
    if (!parsed.success) {
      ctx.addIssue({ code: "custom", path: [accountId], message: "invalid quota auto-refresh setting" });
    }
  }
}).pipe(z.record(z.string(), codexQuotaAutoRefreshEntrySchema));

/**
 * Deliberately permissive. A user's config is not ours to invalidate: a strict
 * entry fails the whole parse, and loadConfig's fallback then backs the file up
 * and returns defaults — losing providers and pool accounts because one key name
 * was too long. Length and charset rules live at the POST/PATCH boundary, where
 * rejecting produces a 400 instead. `.passthrough()` keeps unknown per-key
 * properties across a load -> mutate -> save round trip.
 *
 * Only `key` is load-bearing: admission compares that string and nothing else
 * (src/server/auth-cors.ts isDataPlaneAdmissionSecret). So the secret is the one
 * field that must be a usable string, and every piece of metadata around it
 * degrades instead of taking the credential down with it. Dropping a working key
 * because its `name` was hand-edited to a number would be a silent revocation —
 * and on a remote bind, potentially a server that refuses to start.
 *
 * "Usable" matches admission exactly. The presented token is trimmed before the
 * comparison but the stored value is not, so a key with surrounding whitespace
 * can never match either form of itself. Keeping one would be worse than dropping
 * it: `system-env.ts` and `cli/claude.ts` hand `apiKeys[0].key` to launched
 * clients, so a junk first entry would mask a valid later one.
 */
const pendingApiKeyRotationSchema = z.object({
  id: z.string().trim().min(1).max(256),
  key: z.string().refine(isUsableApiKeySecret),
  createdAt: z.string().datetime({ offset: true }),
  expiresAt: z.string().datetime({ offset: true }),
}).strict();

export const apiKeyEntrySchema = z.object({
  key: z.string().refine(isUsableApiKeySecret),
  // Degrades to "" here; every schema consumer then runs `normalizeApiKeyIds`,
  // which fills it deterministically so the id is stable across loads.
  id: z.string().catch(""),
  name: z.string().catch(""),
  createdAt: z.string().catch(""),
  // A damaged overlap record must never discard the still-authoritative key.
  pendingRotation: pendingApiKeyRotationSchema.optional().catch(undefined),
  // Deliberately NOT `.catch`ed, unlike every field above. Degrading a damaged
  // scope to `undefined` would silently widen the key to the whole catalog,
  // which is the one direction a permission field must never fail. Letting the
  // record fail instead drops the key, so a corrupted scope stops that client
  // rather than promoting it.
  allowedProviders: z.array(z.string().trim().min(1).max(256)).optional(),
  allowedModels: z.array(z.string().trim().min(1).max(256)).optional(),
  // Not `.catch`ed for the same reason: a damaged value must not grant metered spend.
  allowMeteredComboTargets: z.boolean().optional(),
}).passthrough();

/**
 * Durable per-client intent.
 *
 * `.passthrough()` is load-bearing: a binary that only knows `codex` must not
 * erase a key a later version wrote during a field-scoped mutation. And each key
 * degrades on its own — a hand edit of `{"codex": "false", "future": false}`
 * drops `codex` to absent (which reads as ON) and keeps `future`, rather than
 * invalidating the object or, worse, the whole config.
 */
export const clientIntegrationsSchema = z.object({
  codex: z.boolean().optional().catch(undefined),
  grok: z.boolean().optional().catch(undefined),
  "claude-desktop": z.boolean().optional().catch(undefined),
}).passthrough();

/**
 * Opt-in opencode-side request timeouts emitted into the generated opencode provider block.
 * Each field is a positive millisecond count or the literal `false` (disable that wait). A
 * malformed per-field value degrades to undefined (the field is dropped and opencode keeps its
 * native default) rather than rejecting the whole config or emitting an opencode config that
 * opencode would refuse to load. `.passthrough()` keeps a forward-compatible key a later version
 * might add.
 */
const opencodeClientExportTimeout = z.union([z.number().positive().finite(), z.literal(false)]);
export const opencodeClientExportSchema = z.object({
  headerTimeoutMs: opencodeClientExportTimeout.optional().catch(undefined),
  chunkTimeoutMs: opencodeClientExportTimeout.optional().catch(undefined),
  timeoutMs: opencodeClientExportTimeout.optional().catch(undefined),
}).passthrough();

/** omo dialect: an unknown value is dropped so the export falls back to the Chat default. */
export const omoClientExportSchema = z.object({
  api: z.enum(["openai-completions", "openai-responses"]).optional().catch(undefined),
}).passthrough();

export const asideProfileSyncSchema = z.object({
  allProfiles: z.boolean().optional(),
  profiles: z.record(
    z.string().regex(/^(0|[1-9][0-9]*)$/).refine(value => Number.isSafeInteger(Number(value))),
    z.boolean(),
  ).optional(),
  legacyProfileId: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).nullable().optional(),
}).passthrough();

export const agentTaskRecoverySchema = z.object({
  enabled: z.boolean().optional(),
  model: z.string().trim().min(1).optional(),
  timeoutMs: z.number().int().min(1_000).max(120_000).optional(),
  cacheEntries: z.number().int().min(1).max(512).optional(),
  retries: z.number().int().min(0).max(2).optional(),
}).strict();

export const runtimeRoleSchema = z.enum(["standalone", "hub", "client"]);

function canonicalHttpOrigin(value: string): string | null {
  try {
    const parsed = new URL(value);
    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
    if (parsed.username || parsed.password || parsed.pathname !== "/" || parsed.search || parsed.hash) return null;
    return parsed.origin;
  } catch {
    return null;
  }
}

export const managementIngressSchema = z.union([
  z.object({ enabled: z.literal(false) }).strict(),
  z.object({ enabled: z.literal(true), port: z.number().int().min(1).max(65535) }).strict(),
]);

export const hubConfigSchema = z.object({
  managementPublicOrigin: z.string().transform((value, ctx) => {
    const origin = canonicalHttpOrigin(value);
    if (!origin) {
      ctx.addIssue({ code: "custom", message: "must be a canonical http(s) origin without credentials, path, query, or fragment" });
      return z.NEVER;
    }
    return origin;
  }).optional(),
  // Same canonical-origin rule as managementPublicOrigin, and deliberately NOT `.catch`ed:
  // a mistyped data origin must be rejected at write time, because silently dropping it
  // makes `ocx hub invite` print the `http://<hostname>:<port>` fallback that the operator
  // set this field precisely to replace.
  dataPublicOrigin: z.string().transform((value, ctx) => {
    const origin = canonicalHttpOrigin(value);
    if (!origin) {
      ctx.addIssue({ code: "custom", message: "must be a canonical http(s) origin without credentials, path, query, or fragment" });
      return z.NEVER;
    }
    return origin;
  }).optional(),
  // A malformed hand edit disables only the optional ingress. Live writes are rejected by
  // managementIngressConfigError before this load-time degradation can hide the mistake.
  managementIngress: managementIngressSchema.optional().catch(undefined),
}).strict();

const tailscaleUserSchema = z.string().trim().min(1).superRefine((value, ctx) => {
  if (new TextEncoder().encode(value).byteLength > 320) {
    ctx.addIssue({ code: "custom", message: "must be at most 320 UTF-8 bytes" });
  }
  if (/[\x00-\x1f\x7f]/.test(value)) {
    ctx.addIssue({ code: "custom", message: "must not contain ASCII control characters" });
  }
});

export const remoteGuiConfigSchema = z.object({
  allowedTailscaleUsers: z.array(tailscaleUserSchema).max(64).superRefine((users, ctx) => {
    const seen = new Set<string>();
    for (let index = 0; index < users.length; index++) {
      const user = users[index]!;
      if (seen.has(user)) {
        ctx.addIssue({ code: "custom", path: [index], message: "must contain unique users after trimming" });
      }
      seen.add(user);
    }
  }).optional(),
  // Retired (see OcxRemoteGuiConfig): accepted so an existing file still loads, ignored by
  // the pairing path. Removing it from a strict schema would reject the whole config.
  allowInsecureHttp: z.boolean().optional(),
}).strict();

const connectedClientIdSchema = z.enum(["codex", "claude", "claude-desktop", "grok", ...EXPORT_CLIENT_IDS]);
const clientTimestampSchema = z.string().datetime({ offset: true });
const clientTransportSchema = z.enum(["hub", "link"]);
const linkTransportSchema = z.object({
  // Same range as isLinkPort in src/link/ports.ts, restated here because the config schema sits on
  // every install's core path and must not import link code (tests/lab/core-link-boundary.test.ts).
  tunnelPort: z.number().int().min(1024).max(65535),
  linkId: z.string().regex(/^lnk_[0-9a-f]{16}$/),
}).strict();
const clientOriginSchema = z.string().transform((value, ctx) => {
  const origin = canonicalHttpOrigin(value);
  if (!origin) {
    ctx.addIssue({ code: "custom", message: "must be a canonical http(s) origin without credentials, path, query, or fragment" });
    return z.NEVER;
  }
  return origin;
});
export const clientConnectionSchema = z.object({
  serverUrl: clientOriginSchema,
  managementUrl: clientOriginSchema,
  managementTransport: z.enum(["direct", "relay"]),
  transport: clientTransportSchema.optional(),
  link: linkTransportSchema.optional(),
  selectedClients: z.array(connectedClientIdSchema).superRefine((clients, ctx) => {
    if (new Set(clients).size !== clients.length) {
      ctx.addIssue({ code: "custom", message: "must contain unique client ids" });
    }
  }),
  tokenEnv: z.literal("OPENCODEX_API_AUTH_TOKEN"),
  apiKeyId: z.string().trim().min(1).max(256),
  tokenFingerprint: z.string().regex(/^[a-f0-9]{64}$/),
  protocolVersion: z.literal(1),
  connectedAt: clientTimestampSchema,
  catalogFingerprint: z.string().min(1).max(512).optional(),
  // base64 of the pre-connect catalog, or "" for "there was none". Bounded above the
  // catalog size cap so a legitimate snapshot round-trips.
  priorCatalog: z.string().max(64 * 1024 * 1024).optional(),
  catalogSyncedAt: clientTimestampSchema.optional(),
  pendingOperation: z.object({
    kind: z.literal("rotate"),
    rotationId: z.string().trim().min(1).max(256),
    newKeyIssuedAt: clientTimestampSchema,
    oldKeyBackupPath: z.string().min(1),
  }).strict().superRefine((operation, ctx) => {
    const expected = join(getConfigDir(), "service-api-token.prev");
    if (operation.oldKeyBackupPath !== expected) {
      ctx.addIssue({ code: "custom", path: ["oldKeyBackupPath"], message: `must equal ${expected}` });
    }
  }).optional(),
}).strict().superRefine((connection, ctx) => {
  const transport = connection.transport ?? "hub";
  if (transport === "hub" && connection.link !== undefined) {
    ctx.addIssue({ code: "custom", path: ["link"], message: "link is allowed only when transport is link" });
    return;
  }
  if (transport !== "link") return;
  if (!connection.link) {
    ctx.addIssue({ code: "custom", path: ["link"], message: "link is required when transport is link" });
    return;
  }
  if (connection.managementTransport !== "direct") {
    ctx.addIssue({ code: "custom", path: ["managementTransport"], message: "link transport requires direct management transport" });
  }
  if (connection.serverUrl !== connection.managementUrl) {
    ctx.addIssue({ code: "custom", path: ["managementUrl"], message: "link transport requires serverUrl and managementUrl to match" });
  }
  let origin: URL;
  try {
    origin = new URL(connection.serverUrl);
  } catch {
    return;
  }
  if (origin.protocol !== "http:" || origin.hostname !== "127.0.0.1"
    || origin.port !== String(connection.link.tunnelPort)) {
    ctx.addIssue({ code: "custom", path: ["serverUrl"], message: "link transport requires http://127.0.0.1:<tunnelPort>" });
  }
});

/**
 * Codex pool selection policy section.
 *
 * `.strict()` like its neighbour: a typo in an optional feature section should surface as a
 * rejected write rather than a silently ignored key that leaves the operator believing they
 * excluded something.
 */
export const codexAuthMethodSchema = z.enum(["auto", "device-only"]).optional();

export const codexPoolSchema = z.object({
  excludedPlans: z.array(z.string().trim().min(1)).optional(),
  startIdleWindows: z.boolean().optional(),
  requestOwnedAffinity: z.boolean().optional(),
  poolOnly: z.boolean().optional(),
  lowQuotaProtection: z.object({
    enabled: z.boolean(),
    threshold: z.number().finite().min(1).max(100),
    actions: z.object({
      pause: z.boolean(),
      notify: z.boolean(),
      desktop: z.boolean().optional(),
    }).strict(),
    windows: z.object({
      short: z.boolean(),
      weekly: z.boolean(),
    }).strict(),
  }).strict().superRefine((policy, ctx) => {
    if (policy.actions.desktop === true && !policy.actions.notify) {
      ctx.addIssue({ code: "custom", path: ["actions", "desktop"], message: "desktop low-quota notification requires notify" });
    }
    if (!policy.enabled) return;
    if (!policy.actions.pause && !policy.actions.notify) {
      ctx.addIssue({ code: "custom", path: ["actions"], message: "enabled low-quota protection needs an action" });
    }
    if (!policy.windows.short && !policy.windows.weekly) {
      ctx.addIssue({ code: "custom", path: ["windows"], message: "enabled low-quota protection needs a window" });
    }
  }).optional(),
}).strict();

/**
 * Shape guard for the cross-element checks below. Zod runs an array-level check even
 * when an element failed its own validation, and a failed element is not the shape the
 * checker expects — reading `credentials.length` off it would throw out of `safeParse`
 * and take the whole config load with it. Those elements already carry their own issues.
 */
export function isCredentialGroupShape(value: unknown): value is { id: string; credentials: string[] } {
  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
  const group = value as { id?: unknown; credentials?: unknown };
  return typeof group.id === "string"
    && Array.isArray(group.credentials)
    && group.credentials.every(member => typeof member === "string");
}

/**
 * Operator-declared quota domains (`pool.credentialGroups`).
 *
 * Loose enough to hand-write, strict enough that it cannot mean two things: unique group
 * ids, a non-empty member list, provider-qualified members, and each credential in at
 * most one group. Those are not tidiness rules. `classifyCredential` keys a declared
 * domain by group id, so a duplicate id or a credential listed twice merges two quota
 * domains the operator never said were one -- after which the pool counts real capacity
 * once and declines to rotate into it. A bare credential id is ambiguous for the same
 * reason ids are provider-scoped in the auth store, so members carry their provider.
 * {@link credentialGroupIssues} is the single definition, shared with the classifier.
 */
export const credentialGroupsSchema = z.array(z.object({
  id: z.string().trim().min(1),
  credentials: z.array(z.string().trim().min(1)).min(1),
  note: z.string().optional(),
})).superRefine((groups, ctx) => {
  if (!Array.isArray(groups) || !groups.every(isCredentialGroupShape)) return;
  for (const message of credentialGroupIssues(groups)) {
    ctx.addIssue({ code: "custom", message });
  }
});

/**
 * Quota-reset notification section.
 *
 * `.strict()` like its neighbour: a typo in an optional feature section should surface as a
 * rejected write rather than a silently ignored key that leaves the operator believing they
 * enabled something.
 *
 * `pollSeconds` admits 0 (passive-only, no timer) and the resolver clamps anything between 1
 * and the 60-second floor. Bounds live in the resolver rather than here so a hand-edited value
 * degrades to a sane one instead of discarding the whole section.
 */
export const quotaResetNotifySchema = z.object({
  enabled: z.boolean().optional(),
  kinds: z.array(z.enum(["scheduled", "surprise"])).optional(),
  pollSeconds: z.number().int().min(0).optional(),
  // `z.string().url()` accepts any scheme. The payload carries account identity and the hook
  // URL is frequently a bearer-equivalent secret, so an http: sink puts both in cleartext.
  webhookUrl: z.string().url().refine(
    value => { try { return new URL(value).protocol === "https:"; } catch { return false; } },
    { message: "webhookUrl must use https" },
  ).optional(),
  allowPrivateNetwork: z.boolean().optional(),
  timeoutMs: z.number().int().positive().optional(),
  command: z.array(z.string()).optional(),
}).strict();

/**
 * Catalog auto-refresh section (issue #3630).
 * Missing section or enabled flag uses the hourly default-on scheduler.
 *
 * `.strict()` like its neighbour: a typo in an optional feature section should surface as a
 * rejected write rather than a silently ignored key that leaves the operator believing they
 * enabled something.
 *
 * `intervalMinutes` admits 0 (configured but dormant, no timer) and the resolver clamps
 * anything between 1 and the 15-minute floor. Bounds live in the resolver rather than here
 * so a hand-edited value degrades to a sane one instead of discarding the whole section.
 * The 1440 ceiling keeps a hand edit from scheduling the refresh further out than a day,
 * which is operator error far more often than intent.
 */
export const catalogAutoRefreshSchema = z.object({
  enabled: z.boolean().optional(),
  intervalMinutes: z.number().int().min(0).max(1440).optional(),
}).strict();

/**
 * One spend scope's ceiling.
 *
 * `.strict()` for the usual reason and one sharper one. Elsewhere a silently ignored key
 * leaves a feature off that the operator believed was on; here it leaves a BUDGET off, and a
 * budget nobody is enforcing looks exactly like a budget nobody has exceeded. That is #2106 --
 * an undeclared option accepted, persisted, and then read as its default -- aimed at spend.
 *
 * Only positive integers: 0 would read as "no tokens at all" and refuse every request under
 * the scope, which is never what writing a budget means. An operator who wants no ceiling
 * removes the key.
 */
const spendScopeSchema = z.object({
  maxTokens: z.number().int().positive().optional(),
}).strict();

/**
 * Durable spend ceilings (#4546).
 *
 * Absent, empty, and all-scopes-absent are the same thing: observe-only accounting. There is
 * no default ceiling anywhere in this section, deliberately.
 */
export const spendSchema = z.object({
  root: spendScopeSchema.optional(),
  identity: spendScopeSchema.optional(),
  pool: spendScopeSchema.optional(),
  retentionDays: z.number().int().min(1).max(365).optional(),
}).strict();

/**
 * Runtime skills catalog configuration (#5569).
 */
export const skillsConfigSchema = z.object({
  catalog_refresh: z.enum(["per_session", "per_turn"]).optional(),
}).strict();

/**
 * Anonymous telemetry consent state.
 *
 * No endpoint is accepted here: the collector URL is a constant in src/telemetry/sender.ts.
 */
export const telemetryConfigSchema = z.object({
  decision: z.enum(["accepted", "declined"]).optional(),
  decidedAt: clientTimestampSchema.optional(),
  noticeShownAt: clientTimestampSchema.optional(),
}).strict();