@bitkyc08/opencodex 2.75.0 → 2.76.0

package/src/combos/jev.ts

@@ -3,21 +3,38 @@ import {
   providerOutboundPost,
   providerRedirectError,
 } from "../lib/provider-outbound";
-import { resolveProviderApiKey } from "../providers/api-key-resolve";
+import {
+  isKeychainReference,
+  keychainReferenceBelongsToProvider,
+  resolveProviderApiKey,
+} from "../providers/api-key-resolve";
 import { providerMatchesRegistryTransport } from "../providers/registry";
 import type { OcxComboDefaultEffort, OcxConfig, OcxProviderConfig } from "../types";
-import { JEV_MAX_CANDIDATE_FIELD_CHARS } from "./types";
+import {
+  isSystemOneEndpoint,
+  JEV_DECISION_TIMEOUT_DEFAULT_MS,
+  JEV_DECISION_TIMEOUT_MAX_MS,
+  JEV_DECISION_TIMEOUT_MIN_MS,
+  JEV_MAX_CANDIDATE_FIELD_CHARS,
+} from "./types";
 
 export const JEV_PROVIDER_ID = "jev";
 export const JEV_API_URL = "https://api.typesafe.ai/v1/systemone";
 export const JEV_MODEL = "jev-latest";
 
-const JEV_TIMEOUT_MS = 4_000;
-const JEV_MAX_CANDIDATES = 64;
-const JEV_MAX_REQUEST_BYTES = 65_536;
-const JEV_MAX_RESPONSE_BYTES = 65_536;
+export const JEV_MAX_CANDIDATES = 64;
+/** Ollama's System One choice questions accept 2..26 options; other services share the floor. */
+const SELF_HOSTED_MIN_OPTIONS = 2;
+const SELF_HOSTED_MAX_OPTIONS = 26;
+/** Environment names that hold TypeSafe credentials; a self-hosted row may never reference them. */
+const TYPESAFE_ENV_KEYS = new Set(["TYPESAFE_API_KEY", "JEV_API_KEY"]);
+export const JEV_MAX_REQUEST_BYTES = 65_536;
+export const JEV_MAX_RESPONSE_BYTES = 65_536;
 const JEV_OUTBOUND_DEPENDENCIES = {
   isCanonicalUrl: (name: string, url: string) => name === JEV_PROVIDER_ID && url === JEV_API_URL,
+  // Self-hosted decision models (Ollama tev1) listen on plain HTTP loopback. The outbound wrapper
+  // still requires the row's own allowPrivateNetwork and a literal local address for that.
+  allowLocalCleartextPost: true,
 };
 
 const TASK_CHARS = 500;
@@ -74,7 +91,23 @@ export interface JevCandidate {
   modelProfile?: string;
 }
 
+/**
+ * Which kind of service answered a decision. `typesafe` is the canonical System One endpoint,
+ * `systemone` a configured System One-compatible row, `model` an opencodex-routed model.
+ */
+export type JevDecisionBackend = "typesafe" | "systemone" | "model";
+
+/** The backend a combo's decision settings select. A decision model wins over a provider row. */
+export function jevDecisionBackendFor(
+  combo: { decisionProvider?: string | null; decisionModel?: string | null },
+): JevDecisionBackend {
+  if (typeof combo.decisionModel === "string" && combo.decisionModel.trim()) return "model";
+  const provider = typeof combo.decisionProvider === "string" ? combo.decisionProvider.trim() : "";
+  return provider && provider !== JEV_PROVIDER_ID ? "systemone" : "typesafe";
+}
+
 export interface JevDecision {
+  backend: JevDecisionBackend;
   targetKey: string;
   effort: OcxComboDefaultEffort | null;
   gate: "apply" | "missing_key" | "no_choices" | "no_state" | "timeout" | "network" | "redirect" | "http" | "malformed" | "invalid";
@@ -89,6 +122,13 @@ export interface ResolveJevDecisionOptions {
   candidates: readonly JevCandidate[];
   fallback: { targetKey: string; effort: OcxComboDefaultEffort | null };
   config: OcxConfig;
+  /**
+   * Decision service provider id. Omitted or `"jev"` keeps the canonical TypeSafe destination;
+   * any other id names a configured `jev-decision` row (for example a self-hosted Ollama `tev1`).
+   */
+  decisionProvider?: string;
+  /** Decision deadline; values outside 1000..120000 ms keep the four-second default. */
+  timeoutMs?: number;
   signal?: AbortSignal;
   post?: typeof providerOutboundPost;
   now?: () => number;
@@ -400,7 +440,7 @@ export function buildJevState(body: unknown, candidates: readonly JevCandidate[]
   };
 }
 
-function hasJevDecisionState(state: Record<string, unknown>): boolean {
+export function hasJevDecisionState(state: Record<string, unknown>): boolean {
   if (typeof state.task === "string" && state.task.trim()) return true;
   if (isRecord(state.signals) && state.signals.has_image === true) return true;
   return isRecord(state.step)
@@ -431,7 +471,7 @@ function candidateOptions(candidates: readonly JevCandidate[]): Map<string, JevR
   return options;
 }
 
-function candidatesFitRequestBounds(candidates: readonly JevCandidate[]): boolean {
+export function candidatesFitRequestBounds(candidates: readonly JevCandidate[]): boolean {
   if (candidates.length > JEV_MAX_CANDIDATES) return false;
   return candidates.every(candidate => [candidate.key, candidate.provider, candidate.model]
     .every(value => value.length > 0 && value.length <= JEV_MAX_CANDIDATE_FIELD_CHARS)
@@ -445,10 +485,47 @@ function modelProfile(candidate: JevCandidate): string {
     ?? "Configured target with capability unspecified by JEV; judge it only from the supplied request evidence.";
 }
 
-export function buildJevRouteQuestion(candidates: readonly JevCandidate[]): Record<string, unknown> {
-  const options = candidateOptions(candidates);
+function criterionDescription(criterion: JevRouteOption["criterion"]): string {
+  const effort = criterion.reasoning_effort
+    ? `${criterion.reasoning_effort} reasoning effort`
+    : "no reasoning-effort control";
+  return `Target ${criterion.target} (provider ${criterion.provider}, model ${criterion.model}) with ${effort}.`;
+}
+
+/** One allowlisted target/effort option, shared by every decision backend. */
+export interface JevRouteOptionDescriptor {
+  key: string;
+  targetKey: string;
+  effort: OcxComboDefaultEffort | null;
+  description: string;
+}
+
+/** Every allowlisted option in question order; throws on a duplicate choice like the builder. */
+export function jevRouteOptions(candidates: readonly JevCandidate[]): JevRouteOptionDescriptor[] {
+  return [...candidateOptions(candidates)].map(([key, option]) => ({
+    key,
+    targetKey: option.targetKey,
+    effort: option.effort,
+    description: criterionDescription(option.criterion),
+  }));
+}
+
+/**
+ * Build the single `route` choice question.
+ *
+ * TypeSafe receives each option's structured criterion object. `descriptiveCriteria` renders the
+ * same facts as one plain description string per option instead, the portable System One shape
+ * that self-hosted services such as Ollama require ("option keys to descriptions or null").
+ */
+export function buildJevRouteQuestion(
+  candidates: readonly JevCandidate[],
+  options: { descriptiveCriteria?: boolean } = {},
+): Record<string, unknown> {
+  const routeOptions = candidateOptions(candidates);
   const criteria: Record<string, unknown> = {};
-  for (const [choice, option] of options) criteria[choice] = option.criterion;
+  for (const [choice, option] of routeOptions) {
+    criteria[choice] = options.descriptiveCriteria ? criterionDescription(option.criterion) : option.criterion;
+  }
   const modelProfiles: Record<string, string> = {};
   for (const candidate of candidates) modelProfiles[candidate.key] = modelProfile(candidate);
   return {
@@ -468,7 +545,7 @@ export function buildJevRouteQuestion(candidates: readonly JevCandidate[]): Reco
   };
 }
 
-function jevUsage(payload: Record<string, unknown>): Record<string, number> | undefined {
+export function jevUsage(payload: Record<string, unknown>): Record<string, number> | undefined {
   if (!isRecord(payload.usage)) return undefined;
   const usage: Record<string, number> = {};
   for (const [key, value] of Object.entries(payload.usage)) {
@@ -530,12 +607,23 @@ export function parseJevDecision(
   };
 }
 
-function fallbackDecision(
+export function fallbackDecision(
   fallback: ResolveJevDecisionOptions["fallback"],
   gate: Exclude<JevDecision["gate"], "apply">,
   latencyMs: number,
+  backend: JevDecisionBackend,
 ): JevDecision {
-  return { ...fallback, gate, latencyMs };
+  return { backend, ...fallback, gate, latencyMs };
+}
+
+/** The decision deadline: the configured value when in bounds, otherwise the four-second default. */
+export function jevDecisionTimeoutMs(value: number | undefined): number {
+  return value !== undefined
+    && Number.isInteger(value)
+    && value >= JEV_DECISION_TIMEOUT_MIN_MS
+    && value <= JEV_DECISION_TIMEOUT_MAX_MS
+    ? value
+    : JEV_DECISION_TIMEOUT_DEFAULT_MS;
 }
 
 function canonicalJevProvider(config: OcxConfig): OcxProviderConfig {
@@ -549,8 +637,87 @@ function canonicalJevProvider(config: OcxConfig): OcxProviderConfig {
   };
 }
 
+interface JevDecisionEndpoint {
+  name: string;
+  provider: OcxProviderConfig;
+  url: string;
+  model: string;
+  apiKey: string | undefined;
+  /** Self-hosted System One services accept only string option descriptions. */
+  descriptiveCriteria: boolean;
+}
+
+function envReferenceName(value: string): string | undefined {
+  const braced = /^\$\{(\w+)\}$/.exec(value);
+  if (braced) return braced[1];
+  return value.startsWith("$") ? value.slice(1) : undefined;
+}
+
+/**
+ * A self-hosted row may carry only its own secret: never a reference to the TypeSafe environment
+ * keys, and never a keychain entry that belongs to another provider. `null` means refused.
+ */
+function selfHostedApiKey(name: string, apiKey: string | undefined): string | undefined | null {
+  if (!apiKey) return undefined;
+  const envName = envReferenceName(apiKey);
+  if (envName !== undefined && TYPESAFE_ENV_KEYS.has(envName)) return null;
+  if (isKeychainReference(apiKey) && !keychainReferenceBelongsToProvider(apiKey, name)) return null;
+  return resolveProviderApiKey(apiKey)?.trim() || undefined;
+}
+
+/**
+ * Resolve where one decision request goes and which credential it may carry.
+ *
+ * The `jev` id stays pinned to the canonical TypeSafe URL and `jev-latest`: its row key is used
+ * only while the row still matches the registry transport, and the environment fallbacks exist
+ * only for that URL. A retargeted `jev` row therefore keeps today's behavior instead of becoming a
+ * custom destination. Any other id must be an enabled `jev-decision` row whose baseUrl is a
+ * `/systemone` endpoint and which names its own model; only its own key may accompany it, so no
+ * TypeSafe credential can reach a self-hosted service. `undefined` means no usable decision
+ * service (reported through the existing `missing_key` gate).
+ */
+function jevDecisionEndpoint(config: OcxConfig, decisionProvider: string): JevDecisionEndpoint | undefined {
+  const configured = Object.hasOwn(config.providers, decisionProvider)
+    ? config.providers[decisionProvider]
+    : undefined;
+  if (configured?.disabled === true) return undefined;
+  if (decisionProvider === JEV_PROVIDER_ID) {
+    const configuredOwnsJev = configured
+      && providerMatchesRegistryTransport(JEV_PROVIDER_ID, configured);
+    const apiKey = (
+      configuredOwnsJev ? resolveProviderApiKey(configured.apiKey)?.trim() : undefined
+    ) || process.env.TYPESAFE_API_KEY?.trim()
+      || process.env.JEV_API_KEY?.trim();
+    if (!apiKey) return undefined;
+    return {
+      name: JEV_PROVIDER_ID,
+      provider: canonicalJevProvider(config),
+      url: JEV_API_URL,
+      model: JEV_MODEL,
+      apiKey,
+      descriptiveCriteria: false,
+    };
+  }
+  if (configured?.adapter !== "jev-decision" || typeof configured.baseUrl !== "string") return undefined;
+  const url = configured.baseUrl.trim().replace(/\/+$/, "");
+  if (!url || !isSystemOneEndpoint(url)) return undefined;
+  // `jev-latest` is TypeSafe's model name; a self-hosted host must name its own.
+  const model = configured.defaultModel?.trim() || configured.models?.[0]?.trim();
+  if (!model) return undefined;
+  const apiKey = selfHostedApiKey(decisionProvider, configured.apiKey);
+  if (apiKey === null) return undefined;
+  return {
+    name: decisionProvider,
+    provider: configured,
+    url,
+    model,
+    apiKey,
+    descriptiveCriteria: true,
+  };
+}
+
 /**
- * Ask TypeSafe JEV for one allowlisted target/effort decision.
+ * Ask the configured JEV decision service for one allowlisted target/effort decision.
  *
  * Every operational or response failure returns the supplied first-eligible fallback. A caller
  * abort is the exception: request cancellation remains cancellation and is rethrown by identity.
@@ -558,38 +725,40 @@ function canonicalJevProvider(config: OcxConfig): OcxProviderConfig {
 export async function resolveJevDecision(options: ResolveJevDecisionOptions): Promise<JevDecision> {
   const now = options.now ?? Date.now;
   const startedAt = now();
+  const backend = jevDecisionBackendFor({ decisionProvider: options.decisionProvider });
   const failed = (gate: Exclude<JevDecision["gate"], "apply">): JevDecision =>
-    fallbackDecision(options.fallback, gate, Math.max(0, now() - startedAt));
+    fallbackDecision(options.fallback, gate, Math.max(0, now() - startedAt), backend);
 
   if (options.signal?.aborted) throw options.signal.reason;
   if (options.candidates.length === 0) return failed("no_choices");
   if (!candidatesFitRequestBounds(options.candidates)) return failed("invalid");
 
-  const configured = options.config.providers[JEV_PROVIDER_ID];
-  if (configured?.disabled === true) return failed("missing_key");
-  const configuredOwnsJev = configured
-    && providerMatchesRegistryTransport(JEV_PROVIDER_ID, configured);
-  const apiKey = (
-    configuredOwnsJev ? resolveProviderApiKey(configured.apiKey)?.trim() : undefined
-  ) || process.env.TYPESAFE_API_KEY?.trim()
-    || process.env.JEV_API_KEY?.trim();
-  if (!apiKey) return failed("missing_key");
+  const endpoint = jevDecisionEndpoint(options.config, options.decisionProvider ?? JEV_PROVIDER_ID);
+  if (!endpoint) return failed("missing_key");
 
   let requestBody: string;
   try {
+    if (endpoint.descriptiveCriteria) {
+      // Self-hosted choice questions accept 2..26 options; decide locally instead of spending a
+      // round-trip on a request the service will refuse.
+      const optionCount = candidateOptions(options.candidates).size;
+      if (optionCount < SELF_HOSTED_MIN_OPTIONS) return failed("no_choices");
+      if (optionCount > SELF_HOSTED_MAX_OPTIONS) return failed("invalid");
+    }
     const state = buildJevState(options.body, options.candidates);
     if (!hasJevDecisionState(state)) return failed("no_state");
     requestBody = JSON.stringify({
-      model: JEV_MODEL,
+      model: endpoint.model,
       state,
-      questions: buildJevRouteQuestion(options.candidates),
+      questions: buildJevRouteQuestion(options.candidates, { descriptiveCriteria: endpoint.descriptiveCriteria }),
     });
     if (new TextEncoder().encode(requestBody).byteLength > JEV_MAX_REQUEST_BYTES) return failed("invalid");
   } catch {
     return failed("invalid");
   }
 
-  const timeoutSignal = AbortSignal.timeout(JEV_TIMEOUT_MS);
+  const timeoutMs = jevDecisionTimeoutMs(options.timeoutMs);
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
   const signal = options.signal
     ? AbortSignal.any([options.signal, timeoutSignal])
     : timeoutSignal;
@@ -597,12 +766,12 @@ export async function resolveJevDecision(options: ResolveJevDecisionOptions): Pr
 
   try {
     const response = await post(
-      JEV_PROVIDER_ID,
-      canonicalJevProvider(options.config),
-      JEV_API_URL,
+      endpoint.name,
+      endpoint.provider,
+      endpoint.url,
       {
         headers: {
-          Authorization: `Bearer ${apiKey}`,
+          ...(endpoint.apiKey ? { Authorization: `Bearer ${endpoint.apiKey}` } : {}),
           "Content-Type": "application/json",
         },
         body: requestBody,
@@ -612,7 +781,7 @@ export async function resolveJevDecision(options: ResolveJevDecisionOptions): Pr
     );
     if (options.signal?.aborted) throw options.signal.reason;
 
-    const redirectError = await providerRedirectError(response, JEV_API_URL);
+    const redirectError = await providerRedirectError(response, endpoint.url);
     if (redirectError) return failed("redirect");
     if (!response.ok) {
       try { void response.body?.cancel().catch(() => undefined); } catch { /* best effort */ }
@@ -642,6 +811,7 @@ export async function resolveJevDecision(options: ResolveJevDecisionOptions): Pr
     }
     if (options.signal?.aborted) throw options.signal.reason;
     return {
+      backend,
       ...parsed,
       gate: "apply",
       latencyMs: Math.max(0, now() - startedAt),
@@ -655,3 +825,49 @@ export async function resolveJevDecision(options: ResolveJevDecisionOptions): Pr
     return failed("network");
   }
 }
+
+export type JevDecisionProbeResult =
+  | { ok: true; latencyMs: number; message: string }
+  | { ok: false; latencyMs: number; error: string };
+
+/**
+ * Management connection test for one `jev-decision` provider row. It sends a fixed probe task and
+ * no user prompt, and reports only a sanitized gate. Canonical TypeSafe wording is kept for `jev`.
+ */
+export async function probeJevDecisionProvider(
+  config: OcxConfig,
+  name: string,
+  options: Pick<ResolveJevDecisionOptions, "signal" | "post"> = {},
+): Promise<JevDecisionProbeResult> {
+  const canonical = name === JEV_PROVIDER_ID;
+  const label = canonical ? "TypeSafe JEV" : "JEV decision service";
+  const probe = { targetKey: "jev/probe", effort: null } as const;
+  const decision = await resolveJevDecision({
+    body: {
+      input: canonical
+        ? "Verify the configured TypeSafe JEV decision service."
+        : "Verify the configured JEV decision service.",
+    },
+    candidates: [{
+      key: probe.targetKey,
+      provider: "jev",
+      model: "jev-latest",
+      // Self-hosted System One choice questions need at least two options.
+      reasoningEfforts: canonical ? [] : ["low", "high"],
+    }],
+    fallback: probe,
+    config,
+    decisionProvider: name,
+    ...options,
+  });
+  if (decision.gate === "apply") {
+    return { ok: true, latencyMs: decision.latencyMs, message: `Connected. ${label} answered a decision probe.` };
+  }
+  return {
+    ok: false,
+    latencyMs: decision.latencyMs,
+    error: decision.gate === "missing_key"
+      ? (canonical ? "TypeSafe JEV API key is not configured" : "JEV decision service is disabled or not configured")
+      : `${canonical ? "TypeSafe JEV decision probe" : "JEV decision service probe"} failed (${decision.gate})`,
+  };
+}

package/src/combos/types.ts

@@ -1,10 +1,22 @@
-import { isCodexReasoningEffort } from "../reasoning-effort";
+import { isCodexReasoningEffort, isDeclaredReasoningEffort } from "../reasoning-effort";
 import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../codex/catalog/native-models";
 import type { OcxComboConfig, OcxComboCooldownWaitPolicy, OcxComboDefaultEffort, OcxComboDefaultEffortMode, OcxComboReasoningEffortMode, OcxComboStrategy, OcxComboTarget, OcxProviderConfig } from "../types";
-import { COMBO_NAMESPACE, isValidComboId, targetKey } from "./identifiers";
+import { COMBO_NAMESPACE, isValidComboId, resolveComboId, targetKey } from "./identifiers";
+import {
+  CANONICAL_JEV_DECISION_PROVIDER,
+  JEV_DECISION_TIMEOUT_MAX_MS,
+  JEV_DECISION_TIMEOUT_MIN_MS,
+  isSystemOneEndpoint,
+} from "./jev-decision-contract";
 
 export const COMBO_DEFAULT_WAIT_FOR_COOLDOWN_MS = 0;
 export const JEV_MAX_CANDIDATE_FIELD_CHARS = 512;
+export {
+  JEV_DECISION_TIMEOUT_DEFAULT_MS,
+  JEV_DECISION_TIMEOUT_MAX_MS,
+  JEV_DECISION_TIMEOUT_MIN_MS,
+  isSystemOneEndpoint,
+} from "./jev-decision-contract";
 export { COMBO_NAMESPACE, preservesPhysicalComboProvider, isNativeAliasCombo, targetKey, parseComboModelId, comboModelId, comboPublicModelId, comboDisabledModelId, comboDisabledModelSelectors, resolveComboId, isValidComboId } from "./identifiers";
 
 /**
@@ -52,6 +64,12 @@ export interface NormalizedComboConfig {
   nativeAlias: boolean;
   /** Display-only label for the catalog row, or null when unset. */
   displayName: string | null;
+  /** JEV decision service provider id; absent means the canonical `jev` service. */
+  decisionProvider?: string;
+  /** Ordinary inference route used for JEV decisions. */
+  decisionModel?: string;
+  /** JEV decision deadline override; absent keeps the default four-second deadline. */
+  decisionTimeoutMs?: number;
   targets: NormalizedComboTarget[];
 }
 
@@ -102,8 +120,15 @@ export function comboAliasIssues(
 
 export interface ComboValidationOptions {
   requireEnabledTarget?: boolean;
+  /**
+   * Save-time only: also reject a `decisionProvider` row the runtime would skip (disabled, or no
+   * model). Config-file load stays lenient so disabling a referenced row never breaks startup.
+   */
+  requireUsableDecisionService?: boolean;
   /** Full combos map for alias uniqueness checks; omitted during early config load. */
   combos?: Record<string, OcxComboConfig>;
+  /** Ingress selector grammar, injected so combo validation never imports server routing. */
+  normalizeDecisionModel?: (model: string) => string;
   /** Combo being renamed — its stored alias is excluded from uniqueness checks. */
   excludeComboId?: string;
 }
@@ -256,6 +281,72 @@ export function comboConfigIssues(
   if (nativeAlias && (typeof body.displayName !== "string" || body.displayName.trim().length === 0)) {
     issues.push({ path: ["displayName"], message: "displayName is required for native aliases" });
   }
+  if (body.decisionProvider !== undefined && body.decisionProvider !== null) {
+    const decisionProvider = typeof body.decisionProvider === "string" ? body.decisionProvider.trim() : "";
+    if (!decisionProvider) {
+      issues.push({ path: ["decisionProvider"], message: "decisionProvider must be a non-empty provider name" });
+    } else if (body.strategy !== "jev") {
+      issues.push({ path: ["decisionProvider"], message: 'decisionProvider is only valid with strategy "jev"' });
+    } else if (decisionProvider === CANONICAL_JEV_DECISION_PROVIDER) {
+      // Explicit "jev" means exactly what omission means: the canonical TypeSafe service.
+    } else if (!Object.hasOwn(providers, decisionProvider)) {
+      issues.push({
+        path: ["decisionProvider"],
+        message: `decisionProvider "${decisionProvider}" is not configured`,
+      });
+    } else if (providers[decisionProvider]?.adapter !== "jev-decision") {
+      issues.push({
+        path: ["decisionProvider"],
+        message: `decisionProvider "${decisionProvider}" is not a decision service (adapter must be "jev-decision")`,
+      });
+    } else if (!isSystemOneEndpoint(String(providers[decisionProvider]?.baseUrl ?? ""))) {
+      issues.push({
+        path: ["decisionProvider"],
+        message: `decisionProvider "${decisionProvider}" baseUrl must be the full decision endpoint ending in /systemone`,
+      });
+    } else if (options.requireUsableDecisionService && providers[decisionProvider]?.disabled === true) {
+      issues.push({
+        path: ["decisionProvider"],
+        message: `decisionProvider "${decisionProvider}" is disabled`,
+      });
+    } else if (options.requireUsableDecisionService
+      && !providers[decisionProvider]?.defaultModel?.trim()
+      && !providers[decisionProvider]?.models?.[0]?.trim()) {
+      issues.push({
+        path: ["decisionProvider"],
+        message: `decisionProvider "${decisionProvider}" has no model (set defaultModel or models)`,
+      });
+    }
+  }
+  if (body.decisionModel !== undefined && body.decisionModel !== null) {
+    const model = typeof body.decisionModel === "string" ? body.decisionModel.trim() : "";
+    if (!model || model.length > JEV_MAX_CANDIDATE_FIELD_CHARS) {
+      issues.push({ path: ["decisionModel"], message: `decisionModel must be a non-empty string of at most ${JEV_MAX_CANDIDATE_FIELD_CHARS} characters` });
+    } else {
+      if (body.strategy !== "jev") {
+        issues.push({ path: ["decisionModel"], message: 'decisionModel is only valid with strategy "jev"' });
+      }
+      if (body.decisionProvider !== undefined && body.decisionProvider !== null) {
+        issues.push({ path: ["decisionModel"], message: "decisionModel cannot coexist with decisionProvider" });
+      }
+      const comboId = resolveComboId({ combos: options.combos }, options.normalizeDecisionModel?.(model) ?? model);
+      if (comboId === id || (comboId && options.combos?.[comboId]?.strategy === "jev")) {
+        issues.push({ path: ["decisionModel"], message: `decisionModel must not reference ${comboId === id ? "itself" : "a JEV combo"} (combo "${comboId}")` });
+      }
+    }
+  }
+  if (body.decisionTimeoutMs !== undefined && body.decisionTimeoutMs !== null) {
+    if (typeof body.decisionTimeoutMs !== "number" || !Number.isInteger(body.decisionTimeoutMs)
+      || body.decisionTimeoutMs < JEV_DECISION_TIMEOUT_MIN_MS
+      || body.decisionTimeoutMs > JEV_DECISION_TIMEOUT_MAX_MS) {
+      issues.push({
+        path: ["decisionTimeoutMs"],
+        message: `decisionTimeoutMs must be an integer from ${JEV_DECISION_TIMEOUT_MIN_MS} to ${JEV_DECISION_TIMEOUT_MAX_MS}`,
+      });
+    } else if (body.strategy !== "jev") {
+      issues.push({ path: ["decisionTimeoutMs"], message: 'decisionTimeoutMs is only valid with strategy "jev"' });
+    }
+  }
 
   if (!Array.isArray(body.targets) || body.targets.length === 0) {
     issues.push({ path: ["targets"], message: "targets must be a non-empty array" });
@@ -379,6 +470,8 @@ export function comboConfigError(
 export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig {
   const alias = typeof raw.alias === "string" ? raw.alias.trim() : "";
   const displayName = typeof raw.displayName === "string" ? raw.displayName.trim() : "";
+  const decisionProvider = typeof raw.decisionProvider === "string" ? raw.decisionProvider.trim() : "";
+  const decisionModel = typeof raw.decisionModel === "string" ? raw.decisionModel.trim() : "";
   const defaultEffort = typeof raw.defaultEffort === "string" && isCodexReasoningEffort(raw.defaultEffort)
     ? raw.defaultEffort
     : null;
@@ -395,6 +488,10 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
     alias: alias || null,
     nativeAlias: raw.nativeAlias === true,
     displayName: displayName || null,
+    // Explicit "jev" is the default and stays sparse.
+    ...(decisionProvider && decisionProvider !== CANONICAL_JEV_DECISION_PROVIDER ? { decisionProvider } : {}),
+    ...(decisionModel ? { decisionModel } : {}),
+    ...(typeof raw.decisionTimeoutMs === "number" ? { decisionTimeoutMs: raw.decisionTimeoutMs } : {}),
     targets: raw.targets.map(target => ({
       provider: target.provider.trim(),
       model: target.model.trim(),
@@ -410,6 +507,32 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
   };
 }
 
+/**
+ * Load-time stand-in for the ingress synthetic-row grammar: strip a `--fast` suffix, and a
+ * `--<effort>` suffix when Cursor effort rows are on. It reads only the string, so schema
+ * validation needs no server module, model inventory, or Cursor install detection. The
+ * management save path still resolves the exact grammar against the live inventory.
+ */
+export function lexicalDecisionModelBase(model: string, cursorEffortRows: boolean): string {
+  if (model.endsWith("--fast")) return model.slice(0, -"--fast".length);
+  if (!cursorEffortRows) return model;
+  const separator = model.lastIndexOf("--");
+  if (separator <= 0) return model;
+  const effort = model.slice(separator + 2);
+  return effort !== "none" && isDeclaredReasoningEffort(effort) ? model.slice(0, separator) : model;
+}
+
+/**
+ * Whether removing `provider` would leave this stored combo invalid: a target uses it, or the
+ * combo names it as its JEV decision service. The canonical `jev` id stays valid without a row.
+ */
+export function comboDependsOnProvider(combo: OcxComboConfig, provider: string): boolean {
+  if (combo.targets.some(target => target.provider === provider)) return true;
+  if (typeof combo.decisionModel === "string" && combo.decisionModel.trim().startsWith(`${provider}/`)) return true;
+  const decisionProvider = typeof combo.decisionProvider === "string" ? combo.decisionProvider.trim() : "";
+  return decisionProvider === provider && provider !== CANONICAL_JEV_DECISION_PROVIDER;
+}
+
 export function comboDefaultEffort(
   config: { combos?: Record<string, OcxComboConfig> },
   id: string,

package/src/config/diagnostics.ts

@@ -64,6 +64,7 @@ import {
   remoteGuiConfigSchema,
   runtimeRoleSchema,
   spendSchema,
+  chatgptDesktopSchema,
   compactionRoutingSchema,
   skillsConfigSchema,
   memoryModelsSchema,
@@ -102,6 +103,9 @@ function validFileConfigDiagnostics(config: OcxConfig, rawParsed: unknown): Conf
   const rawEffort = rawClaudeSubagentEffort(rawParsed);
   const normalized = normalizeClaudeSubagentEffort(normalizeNativeSubagentSync(config, rawParsed), rawParsed);
   const warnings = configPlaceholderWarnings(normalized);
+  if (normalized.chatgptDesktop?.appServerShim === true && process.platform !== "darwin") {
+    warnings.push("chatgptDesktop.appServerShim is experimental and macOS only; ignored on this platform");
+  }
   warnings.push(...inheritedFastWireConflictProviderNames(normalized).map(inheritedFastWireConflictWarning));
   warnings.push(...degradedCodexAccountPriorityWarnings(rawParsed, normalized));
   warnings.push(...degradedListenerWarnings(rawParsed, normalized));
@@ -463,6 +467,15 @@ function showCodexCreditsError(value: unknown): string | null {
   return "schema_invalid: showCodexCredits: must be a boolean or omitted";
 }
 
+function creditCodexAccountIdsError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "creditCodexAccountIds")) return null;
+  const ids = raw.creditCodexAccountIds;
+  if (ids === undefined) return null;
+  if (Array.isArray(ids) && ids.every(id => typeof id === "string" && /^[a-zA-Z0-9._-]{1,64}$/.test(id))) return null;
+  return "schema_invalid: creditCodexAccountIds: must be an array of account ids or omitted";
+}
+
 function oauthOpenBrowserError(value: unknown): string | null {
   const raw = rawConfigRecord(value);
   if (!raw || !Object.hasOwn(raw, "oauthOpenBrowser")) return null;
@@ -619,6 +632,10 @@ function skillsConfigError(value: unknown): string | null {
 }
 
 export function validateConfigCandidate(value: unknown): { ok: true; config: OcxConfig } | { ok: false; error: string } {
+  const chatgptDesktop = rawConfigRecord(value)?.chatgptDesktop;
+  if (chatgptDesktop !== undefined && !chatgptDesktopSchema.safeParse(chatgptDesktop).success) {
+    return { ok: false, error: "schema_invalid: chatgptDesktop: requires an optional boolean appServerShim and no other fields" };
+  }
   const compactionRouting = rawConfigRecord(value)?.compactionRouting;
   if (compactionRouting !== undefined && !compactionRoutingSchema.safeParse(compactionRouting).success) {
     return { ok: false, error: "schema_invalid: compactionRouting: requires a nonblank model, an optional valid reasoningEffort, and optional non-repeating triggers drawn from \"manual\" and \"auto\"" };
@@ -654,6 +671,7 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
     ?? dropCodexSafetyBufferingError(value)
     ?? oauthOpenBrowserError(value)
     ?? showCodexCreditsError(value)
+    ?? creditCodexAccountIdsError(value)
     ?? runtimeRoleError(value)
     ?? remoteGuiConfigError(value)
     ?? clientConnectionConfigError(value)