@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
194 lines (180 loc) • 9.29 kB
text/typescript
/**
* The Codex settings a Remote Link Home decides for its Children (#6957).
*
* A link Child relays every model request to its Home, so everything the Home's proxy applies
* per request already follows the Home: effort caps, the sub-agent roster and fallback, the
* injection prompt, sidecar and compaction routing, and the catalog itself (served by
* `/v1/catalog`). What does NOT follow is the part of the Home's OpenCodex config that the
* injector writes into the Child's own Codex `config.toml`. This module carries exactly that
* part, which is every OpenCodex config field the Codex injection plan reads that is a policy
* decision rather than a fact about the Child's own listener:
*
* - `fastMode` -> `[features] fast_mode`
* - `multiAgentMode` -> the native `features.multi_agent_v2` reconcile (v1 mode)
* - `webSearchSidecar.enabled` -> the root `web_search` switch
* - `syncCodexSubagentDefaults` + `injectionModel` + `injectionEffort` -> the managed
* `[agents]` defaults
*
* Root `model_reasoning_effort` and the `desktop.*` picker keys are Codex app settings that
* OpenCodex never writes on any machine, so they are deliberately not part of this document.
* Listener facts (port, hostname, Desktop authless and client compaction routing forms, resume
* history) stay the Child's own because they describe how the Child's Codex reaches the Child.
*
* It rides on its own authenticated link read rather than inside the catalog because the
* catalog bytes are written verbatim to the Child's catalog file. The Child's
* injector writes the local `model_catalog_json` binding.
*/
import { createHash } from "node:crypto";
import { hostname } from "node:os";
import type { OcxConfig } from "../types";
export const HOME_CODEX_SETTINGS_VERSION = 1;
const MULTI_AGENT_MODES = ["v1", "default", "v2", "v2-plaintext"] as const;
type MultiAgentMode = (typeof MULTI_AGENT_MODES)[number];
export interface HomeCodexSettings {
/** null: the Home leaves `fast_mode` alone. */
fastMode: boolean | null;
/** null: the Home has no explicit mode. */
multiAgentMode: MultiAgentMode | null;
webSearchSidecarEnabled: boolean;
subagentDefaults: { model: string; reasoningEffort: string | null } | null;
}
export interface HomeCodexSettingsDocument {
version: typeof HOME_CODEX_SETTINGS_VERSION;
home: { name: string; version: string };
settings: HomeCodexSettings;
}
const NAME_MAX = 255;
const VALUE_MAX = 256;
function safeLabel(value: string, max: number): string | null {
const trimmed = value.trim();
if (!trimmed || trimmed.length > max) return null;
for (const character of trimmed) {
const code = character.codePointAt(0) ?? 0;
if (code < 0x20 || code === 0x7f || (code >= 0x202a && code <= 0x202e) || (code >= 0x2066 && code <= 0x2069)) return null;
}
return trimmed;
}
export function projectHomeCodexSettings(config: OcxConfig, version: string): HomeCodexSettingsDocument {
const mode = config.multiAgentMode;
// Same predicate as `subagentDefaultSyncEffective` (src/config/diagnostics.ts), inlined so
// this module stays inside the src/link import boundary.
const sync = config.syncCodexSubagentDefaults === true && Boolean(config.injectionModel?.trim());
const effort = config.injectionEffort?.trim();
return {
version: HOME_CODEX_SETTINGS_VERSION,
home: { name: safeLabel(hostname(), NAME_MAX) ?? "Home", version },
settings: {
fastMode: typeof config.fastMode === "boolean" ? config.fastMode : null,
multiAgentMode: mode && (MULTI_AGENT_MODES as readonly string[]).includes(mode) ? mode : null,
webSearchSidecarEnabled: config.webSearchSidecar?.enabled !== false,
subagentDefaults: sync
? { model: config.injectionModel!.trim(), reasoningEffort: effort ? effort : null }
: null,
},
};
}
function exactKeys(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
if (!value || typeof value !== "object" || Array.isArray(value)) return false;
const actual = Object.keys(value);
return actual.length === keys.length && actual.every(key => keys.includes(key));
}
/** Strict parse: an unknown field, a wrong type or an unsafe label rejects the whole document. */
export function parseHomeCodexSettingsDocument(value: unknown): HomeCodexSettingsDocument | null {
if (!exactKeys(value, ["version", "home", "settings"]) || value.version !== HOME_CODEX_SETTINGS_VERSION) return null;
const home = value.home;
if (!exactKeys(home, ["name", "version"]) || typeof home.name !== "string" || typeof home.version !== "string") return null;
const name = safeLabel(home.name, NAME_MAX);
const homeVersion = safeLabel(home.version, 64);
if (!name || !homeVersion) return null;
const s = value.settings;
if (!exactKeys(s, ["fastMode", "multiAgentMode", "webSearchSidecarEnabled", "subagentDefaults"])) return null;
if (s.fastMode !== null && typeof s.fastMode !== "boolean") return null;
if (s.multiAgentMode !== null && !(MULTI_AGENT_MODES as readonly unknown[]).includes(s.multiAgentMode)) return null;
if (typeof s.webSearchSidecarEnabled !== "boolean") return null;
let subagentDefaults: HomeCodexSettings["subagentDefaults"] = null;
if (s.subagentDefaults !== null) {
const d = s.subagentDefaults;
if (!exactKeys(d, ["model", "reasoningEffort"]) || typeof d.model !== "string") return null;
const model = safeLabel(d.model, VALUE_MAX);
if (!model) return null;
let reasoningEffort: string | null = null;
if (d.reasoningEffort !== null) {
if (typeof d.reasoningEffort !== "string" || !/^[a-z][a-z0-9_-]{0,31}$/.test(d.reasoningEffort)) return null;
reasoningEffort = d.reasoningEffort;
}
subagentDefaults = { model, reasoningEffort };
}
return {
version: HOME_CODEX_SETTINGS_VERSION,
home: { name, version: homeVersion },
settings: {
fastMode: s.fastMode as boolean | null,
multiAgentMode: s.multiAgentMode as MultiAgentMode | null,
webSearchSidecarEnabled: s.webSearchSidecarEnabled,
subagentDefaults,
},
};
}
/** The Child's config as the Codex injector should see it: local listener facts, Home policy. */
export function overlayHomeCodexSettings(config: OcxConfig, settings: HomeCodexSettings): OcxConfig {
const next: OcxConfig = {
...config,
webSearchSidecar: { ...(config.webSearchSidecar ?? {}), enabled: settings.webSearchSidecarEnabled },
};
if (settings.fastMode === null) delete next.fastMode;
else next.fastMode = settings.fastMode;
if (settings.multiAgentMode === null) delete next.multiAgentMode;
else next.multiAgentMode = settings.multiAgentMode;
if (settings.subagentDefaults) {
next.injectionModel = settings.subagentDefaults.model;
next.syncCodexSubagentDefaults = true;
if (settings.subagentDefaults.reasoningEffort) next.injectionEffort = settings.subagentDefaults.reasoningEffort;
else delete next.injectionEffort;
} else {
next.syncCodexSubagentDefaults = false;
}
return next;
}
/** One line per applied value, for `ocx sync`, `ocx status` and the dashboard. */
export function describeHomeCodexSettings(settings: HomeCodexSettings): string[] {
const d = settings.subagentDefaults;
return [
`fast mode: ${settings.fastMode === null ? "unset" : settings.fastMode ? "on" : "off"}`,
`multi-agent mode: ${settings.multiAgentMode ?? "default"}`,
`web search sidecar: ${settings.webSearchSidecarEnabled ? "on" : "off"}`,
`native sub-agent defaults: ${d ? `${d.model}${d.reasoningEffort ? ` (${d.reasoningEffort})` : ""}` : "not synced"}`,
];
}
/** 64 lowercase hex digits: the only form a settings digest takes on the wire. */
export const CODEX_SETTINGS_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
/**
* The exact bytes {@link codexSettingsDigest} hashes: compact UTF-8 JSON in a fixed key order,
*
* {"version":1,"settings":{"fastMode":…,"multiAgentMode":…,"webSearchSidecarEnabled":…,
* "subagentDefaults":null|{"model":…,"reasoningEffort":…}}}
*
* This is a published contract (GOAT's hub recomputes it byte for byte), so the order is written
* out here rather than left to a canonicalizer, and every value is copied by name: whatever key
* order or extra field the input object has, the output is the same.
*/
export function codexSettingsDigestPayload(settings: HomeCodexSettings): string {
const d = settings.subagentDefaults;
return JSON.stringify({
version: HOME_CODEX_SETTINGS_VERSION,
settings: {
fastMode: settings.fastMode,
multiAgentMode: settings.multiAgentMode,
webSearchSidecarEnabled: settings.webSearchSidecarEnabled,
subagentDefaults: d ? { model: d.model, reasoningEffort: d.reasoningEffort } : null,
},
});
}
/**
* `appliedCodexSettingsDigest` (OCX-6b): lowercase hex SHA-256 of
* {@link codexSettingsDigestPayload}. It covers the applied values only, never the Home's name or
* version, so a Home and a Child that applied the same values agree, and any value change differs.
* It carries no setting value, so it is safe wherever `ocx status --json` goes.
*/
export function codexSettingsDigest(settings: HomeCodexSettings): string {
return createHash("sha256").update(codexSettingsDigestPayload(settings), "utf8").digest("hex");
}