@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,390 lines • 60.5 kB
text/typescript
import { constants, copyFileSync, existsSync, readFileSync, statSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { atomicWriteFile } from "../config";
import { applyEol, dominantEol, isLoopbackHostname, providerBaseHost } from "../codex/inject";
import {
grokDefaultReasoningEffort,
grokReasoningEffortOption,
sanitizeGrokReasoningEfforts,
} from "./effort";
export interface GrokInjectModel {
id: string;
name?: string;
contextWindow?: number;
/** Catalog ladder. Empty or absent omits every thinking-intensity field. */
reasoningEfforts?: string[];
defaultReasoningEffort?: string;
}
export interface GrokInjectResult {
ok: boolean;
changed: boolean;
message: string;
skippedReason?: "no-grok-home" | "orphaned-marker" | "non-loopback";
}
const BEGIN_MARKER = "# >>> opencodex managed block — do not edit (removed by `ocx stop`) >>>";
const END_MARKER = "# <<< opencodex managed block <<<";
// Grok 0.2.109 (2026-07-21) shipped working [model_providers.<id>] inheritance: base_url,
// api_backend, api_key, and extra_headers declared on the provider are applied to inference
// routing for inheriting models (verified in grok-build's with_provider_defaults →
// resolve_model_list → sampling_config_for_model → SamplingClient chain). We emit one shared
// [model_providers.opencodex] table and each [model.*] references it via model_provider.
/**
* INTERNAL API shared with `./inspect` (WP2, devlog 260803_integrations_toggle_all/012).
* The inspector and the writer are its only callers — one parser for one fence, so a
* read and a strip can never disagree about where our block starts and stops.
*/
export interface ManagedRegion {
start: number;
end: number;
orphaned: boolean;
}
function tomlString(value: string): string {
return JSON.stringify(value);
}
/**
* INTERNAL API shared with `./inspect`, so the reader and the writer resolve the
* authoritative home identically (GROK_HOME, then ~/.grok). Not a public surface.
*/
export function resolveGrokHome(grokHome?: string): string {
return grokHome ?? (process.env.GROK_HOME || join(homedir(), ".grok"));
}
/** INTERNAL API shared with `./inspect` — a missing home is a STATE, not an error. */
export function isDirectory(path: string): boolean {
try {
return statSync(path).isDirectory();
} catch {
return false;
}
}
/** INTERNAL API — see `ManagedRegion` above. Not a public fence-parsing surface. */
export function findManagedRegion(content: string): ManagedRegion | null {
const markerLine = (marker: string): RegExp =>
new RegExp(`^[ \\t]*${marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[ \\t]*$`, "gm");
const begin = markerLine(BEGIN_MARKER).exec(content);
if (!begin) return null;
const end = markerLine(END_MARKER);
end.lastIndex = begin.index + begin[0].length;
const endMatch = end.exec(content);
if (!endMatch) return { start: begin.index, end: content.length, orphaned: true };
return { start: begin.index, end: endMatch.index + endMatch[0].length, orphaned: false };
}
/**
* A TOML key segment as it may be spelled in a table header: bare, basic string, or literal
* string. All three spellings of the same key address the SAME table, so both segments of a
* `[model.<alias>]` header must be canonicalized before comparison.
*/
const KEY_SEGMENT = String.raw`(?:[A-Za-z0-9_-]+|"(?:[^"\\]|\\.)*"|'[^']*')`;
const DOTTED_KEY = String.raw`${KEY_SEGMENT}(?:[ \t]*\.[ \t]*${KEY_SEGMENT})*`;
/** One complete TOML table-header line; paired brackets reject array-value lookalikes. */
const TABLE_HEADER_LINE = new RegExp(
String.raw`^[ \t]*(?:\[\[[ \t]*(${DOTTED_KEY})[ \t]*\]\]|\[[ \t]*(${DOTTED_KEY})[ \t]*\])[ \t]*(?:#[^\r\n]*)?$`,
);
interface TomlTableHeader {
index: number;
length: number;
segments: string[];
array: boolean;
}
interface TomlStructure {
view: string;
headers: TomlTableHeader[];
containerRootLineStarts: Set<number>;
}
/** End of a TOML multi-line basic/literal string, or EOF when it is unclosed. */
function tomlMultilineStringEnd(content: string, start: number, quote: '"' | "'"): number {
let cursor = start + 3;
while (cursor < content.length) {
if (quote === '"' && content[cursor] === "\\") {
cursor += 2;
continue;
}
if (content[cursor] === quote
&& content[cursor + 1] === quote
&& content[cursor + 2] === quote) {
let end = cursor + 3;
// TOML permits one or two quote characters immediately before the closing delimiter.
if (content[end] === quote) {
end += 1;
if (content[end] === quote) end += 1;
}
return end;
}
cursor += 1;
}
return content.length;
}
/** Find one TOML string value's exact source span; semantic decoding uses Bun's parser. */
function tomlStringSpanAt(content: string, start: number): { end: number } | null {
const quote = content[start];
if (quote !== '"' && quote !== "'") return null;
if (content[start + 1] === quote && content[start + 2] === quote) {
const end = tomlMultilineStringEnd(content, start, quote);
const token = content.slice(start, end);
if (token.length < 6 || !token.endsWith(quote.repeat(3))) return null;
return { end };
}
for (let cursor = start + 1; cursor < content.length; cursor += 1) {
const char = content[cursor]!;
if (char === "\r" || char === "\n") return null;
if (quote === '"' && char === "\\") {
cursor += 1;
continue;
}
if (char === quote) {
return { end: cursor + 1 };
}
}
return null;
}
/** Find the matching end of one inline table / array while skipping strings and comments. */
function tomlContainerEnd(content: string, start: number): number | null {
const opener = content[start];
if (opener !== "{" && opener !== "[") return null;
const stack: string[] = [opener];
for (let index = start + 1; index < content.length;) {
const char = content[index]!;
if (char === "#") {
const newline = content.indexOf("\n", index);
index = newline === -1 ? content.length : newline + 1;
continue;
}
if (char === '"' || char === "'") {
const span = tomlStringSpanAt(content, index);
if (span === null) return null;
index = span.end;
continue;
}
if (char === "{" || char === "[") stack.push(char);
else if (char === "}" || char === "]") {
const expected = char === "}" ? "{" : "[";
if (stack.pop() !== expected) return null;
if (stack.length === 0) return index + 1;
}
index += 1;
}
return null;
}
/**
* A same-length lexical projection for structural scans. Triple-quoted string bytes become
* spaces while line endings and every byte outside those values keep their original offsets.
*/
function tomlStructuralView(content: string): string {
let state: "code" | "comment" | "basic" | "literal" = "code";
let cursor = 0;
let output = "";
for (let index = 0; index < content.length;) {
const char = content[index]!;
if (state === "comment") {
if (char === "\n") state = "code";
index += 1;
continue;
}
if (state === "basic") {
if (char === "\\") index += 2;
else {
if (char === '"') state = "code";
index += 1;
}
continue;
}
if (state === "literal") {
if (char === "'") state = "code";
index += 1;
continue;
}
if (char === "#") {
state = "comment";
index += 1;
continue;
}
if (char === '"' || char === "'") {
if (content[index + 1] === char && content[index + 2] === char) {
const end = tomlMultilineStringEnd(content, index, char);
output += content.slice(cursor, index);
output += content.slice(index, end).replace(/[^\r\n]/g, " ");
cursor = end;
index = end;
continue;
}
state = char === '"' ? "basic" : "literal";
}
index += 1;
}
return output.length === 0 ? content : output + content.slice(cursor);
}
/** Update array / inline-table nesting for one non-header line in the structural view. */
function tomlContainerDepthAfterLine(line: string, initialDepth: number): number {
let depth = initialDepth;
let state: "code" | "basic" | "literal" = "code";
for (let index = 0; index < line.length;) {
const char = line[index]!;
if (state === "basic") {
if (char === "\\") index += 2;
else {
if (char === '"') state = "code";
index += 1;
}
continue;
}
if (state === "literal") {
if (char === "'") state = "code";
index += 1;
continue;
}
if (char === "#") break;
if (char === '"' || char === "'") {
state = char === '"' ? "basic" : "literal";
index += 1;
continue;
}
if (char === "[" || char === "{") depth += 1;
else if (char === "]" || char === "}") depth = Math.max(0, depth - 1);
index += 1;
}
return depth;
}
/**
* Find real table headers and assignment-eligible lines while excluding arrays, inline tables,
* comments, and multi-line strings. Offsets remain exact because `view` is length-preserving.
*/
function analyzeTomlStructure(content: string): TomlStructure {
const view = tomlStructuralView(content);
const headers: TomlTableHeader[] = [];
const containerRootLineStarts = new Set<number>();
let depth = 0;
for (let lineStart = 0; lineStart <= view.length;) {
const newline = view.indexOf("\n", lineStart);
const lineEnd = newline === -1 ? view.length : newline;
const rawLine = view.slice(lineStart, lineEnd);
const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
const header = depth === 0 ? TABLE_HEADER_LINE.exec(line) : null;
if (header) {
const dottedKey = header[1] ?? header[2]!;
headers.push({
index: lineStart,
length: header[0].length,
segments: canonicalDottedKey(dottedKey),
array: header[1] !== undefined,
});
} else {
if (depth === 0) containerRootLineStarts.add(lineStart);
depth = tomlContainerDepthAfterLine(line, depth);
}
if (newline === -1) break;
lineStart = newline + 1;
}
return { view, headers, containerRootLineStarts };
}
/** Resolve a header key segment (bare / basic / literal) to the key it actually addresses. */
function canonicalKeySegment(raw: string): string {
if (raw.startsWith('"')) return decodeTomlBasicString(raw.slice(1, -1));
if (raw.startsWith("'")) return raw.slice(1, -1); // literal strings have no escapes
return raw;
}
/** Split a TOML dotted key without treating dots inside quoted segments as separators. */
function canonicalDottedKey(raw: string): string[] {
return [...raw.matchAll(new RegExp(KEY_SEGMENT, "g"))]
.map(match => canonicalKeySegment(match[0]!));
}
/**
* `[model.<alias>]` table headers the USER owns (outside our fence) — reserved for collisions.
* TOML admits equivalent header spellings for BOTH segments (`["model"."ocx-mine"]`,
* `['model'.ocx-mine]`, `[ model . ocx-mine ]`); all of them redefine the same table, so each
* form is canonicalized before it is reserved. A deeper header only creates an implicit
* parent, so reserve it only for the conservative path used with malformed user TOML.
*/
function userModelAliases(content: string, region: ManagedRegion | null, includeNested = false): Set<string> {
const outsideManagedRegion = region
? content.slice(0, region.start) + content.slice(region.end)
: content;
const aliases = new Set<string>();
for (const header of analyzeTomlStructure(outsideManagedRegion).headers) {
if (header.segments[0] !== "model"
|| (includeNested ? header.segments.length < 2 : header.segments.length !== 2)) continue;
aliases.add(header.segments[1]!);
}
return aliases;
}
/** The api_key literal every generated entry carries. It is necessary, but not ownership alone. */
const OPENCODEX_API_KEY = "opencodex-loopback";
const OPENCODEX_GROK_MARKER = "x-opencodex-grok";
/** The provider id opencodex owns inside ~/.grok/config.toml. */
const OPENCODEX_PROVIDER_ID = "opencodex";
/** A plain `[model.<alias>]` table outside the fence that opencodex itself wrote. */
interface OrphanTable {
alias: string;
/** The model id this entry routes to — used to find its replacement alias. */
modelId: string;
/** Explicit markers authorize teardown; legacy fingerprints authorize replacement only. */
ownership: "explicit" | "legacy";
/** Offsets into the NORMALIZED content: header start .. next header start (or EOF). */
start: number;
end: number;
/** Re-serialized child tables may be separated from the parent by unrelated tables. */
additionalRanges: Array<{ start: number; end: number }>;
}
/** `key = "value"` / `key = value` pairs at the top level of one table body. */
function tableBodyKeys(body: string): Map<string, string> {
const keys = new Map<string, string>();
const structure = analyzeTomlStructure(body);
// Bare keys only: a quoted dotted segment could otherwise split a quoted value
// containing a dot.
const assignment =
/^[ \t]*([A-Za-z0-9_-]+(?:[ \t]*\.[ \t]*[A-Za-z0-9_-]+)*)[ \t]*=[ \t]*(.*?)[ \t]*$/gm;
for (const match of structure.view.matchAll(assignment)) {
if (!structure.containerRootLineStarts.has(match.index!)) continue;
const path = match[1]!.split(".").map(part => part.trim());
const raw = match[2]!;
const value = raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')
? decodeTomlBasicString(raw.slice(1, -1))
: raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")
? raw.slice(1, -1) // TOML literal strings do not process escapes.
: raw;
if (path.length === 1) {
if (!keys.has(path[0]!)) keys.set(path[0]!, value);
continue;
}
// Dotted keys re-open a nested namespace: `extra_headers.k = v` is the key `k` of the
// sub-table `extra_headers`, which a folded-body reader must be able to see. Rebuild
// the inline-table spelling that hasInlineOwnershipMarker matches (bare word booleans
// and numbers keep their TOML spelling — no quoting, so the regex is unchanged).
let suffix = value;
for (let level = path.length - 1; level >= 1; level -= 1) {
const prefixKey = path.slice(0, level).join(".");
const inner = `${JSON.stringify(path[level]!)} = ${suffix}`;
suffix = `{ ${inner} }`;
const existing = keys.get(prefixKey);
if (existing === undefined || !existing.startsWith("{")) {
keys.set(prefixKey, suffix);
} else {
keys.set(prefixKey, `{ ${existing.slice(2, -2)}, ${inner} }`);
}
}
}
return keys;
}
/** Is this base_url pointed at the local machine? */
function isLoopbackBaseUrl(value: string | undefined): boolean {
if (!value) return false;
try {
return isLoopbackHostname(new URL(value).hostname);
} catch {
return false;
}
}
/** Exact marker emitted inside every modern generated model table. */
function hasInlineOwnershipMarker(value: string | undefined): boolean {
// The reconstructed fold of a Grok dotted re-serialization writes bare `1` for the
// boolean literal, so both `= "1"` and `= 1` spellings are accepted here.
return value !== undefined
&& /^\{[ \t]*["']x-opencodex-grok["'][ \t]*=[ \t]*(?:"1"|'1'|1)[ \t]*\}$/.test(value);
}
/** Historical deterministic alias, including collision suffixes allocated by the writer. */
function isGeneratedAliasForModel(alias: string, modelId: string): boolean {
const base = `ocx-${modelId.replace(/[^A-Za-z0-9_-]/g, "-")}`;
if (alias === base) return true;
if (!alias.startsWith(`${base}-`)) return false;
const suffix = alias.slice(base.length + 1);
return /^[1-9][0-9]*$/.test(suffix) && Number(suffix) >= 2;
}
/** Pre-marker auto-generated row shape. Manual rows never carried the generated name. */
function isLegacyGeneratedTable(alias: string, keys: ReadonlyMap<string, string>): boolean {
const modelId = keys.get("model");
return modelId !== undefined
&& modelId.length > 0
&& keys.get("api_backend") === "chat_completions"
&& keys.get("name") === `OCX ${modelId}`
&& isGeneratedAliasForModel(alias, modelId);
}
/** Classify a direct provider/model id without stealing a slash-shaped configured combo alias. */
function isDisabledProviderModelId(
modelId: string,
disabledProviderNamespaces: ReadonlySet<string> | undefined,
comboPublicModelIds: ReadonlySet<string> | undefined,
): boolean {
if (!disabledProviderNamespaces || comboPublicModelIds?.has(modelId)) return false;
const slash = modelId.indexOf("/");
return slash > 0
&& slash < modelId.length - 1
&& disabledProviderNamespaces.has(modelId.slice(0, slash));
}
/**
* Model tables OUTSIDE the fence that opencodex itself wrote (#511).
*
* These are entries from a version that predates the markers (or predates
* `context_window`). Because they sit outside the fence, `userModelAliases` reserves
* their aliases as user-owned and the writer routes around them with a `-2` suffix — so
* every sync adds a CORRECT duplicate and never removes the stale original. Grok then
* resolves the original, finds no `context_window`, and falls back to its own 200k.
*
* Ownership is CONJUNCTIVE and deliberately strict, because a false positive deletes a
* hand-written user model. The public manual recipe intentionally uses the same loopback key,
* endpoint, and Responses backend, so those fields are not ownership proof. We additionally
* require either the durable generated marker or the exact pre-marker legacy fingerprint:
* - a plain `[model.x]` header (never `[[model.x]]` / `[model.x.sub]` — those spellings
* mark human authorship and stay reserved);
* - `api_key` equal to our own literal;
* - a loopback `base_url`, so an entry that merely copied our key while pointing at a
* remote host is left alone.
* - `x-opencodex-grok = "1"` in generated inline/child extra_headers, OR the historical
* chat_completions + `name = "OCX <model>"` + deterministic generated alias shape.
* - PROVIDER-INHERITANCE shape: `model_provider = "opencodex"` with no api_key/base_url of
* its own, adopting the verdict of the `[model_providers.opencodex]` table it references
* (the current block shape carries no per-model evidence; this mirrors Codex-side
* classifyCodexRouting).
* A loopback base_url ALONE is not enough: aiming your own model at the local proxy is a
* legitimate thing to do.
*
* Also sweeps orphaned `[model_providers.opencodex]` blocks from a previous managed block
* that used the provider-inheritance shape. Grok's re-serializer promotes the inline
* `extra_headers = { ... }` into a separate `[model_providers.<id>.extra_headers]`
* sub-table, which can split the parent's body (its own keys then live inside the child's
* span) and may interleave user tables between the parent and its children, so each
* provider's body is FOLDED with all its same-provider descendants before judging, and
* the removal span covers them by their exact ranges. The fenced provider is excluded
* from that sweep (the splice owns it) but still counts as ownership evidence, so
* teardown does not orphan models that inherit from it. The
* durable marker lives on the provider (never on the inheriting model), so the sweep is
* what keeps explicit ownership of inherited entries verifiable after a rewrite.
*/
function findOpencodexOrphans(content: string, region: ManagedRegion | null): OrphanTable[] {
const orphans: OrphanTable[] = [];
// A pre-fence orphan's body must stop AT the fence. The managed block opens with a
// COMMENT, not a table header, so a span that runs to "the next table header" swallows
// the BEGIN marker whenever no other table separates them — and removing the orphan then
// deletes the fence opener itself, which strands the END marker and makes every later
// sync re-append a block (the #511 duplicate loop, one layer down).
// `region` is null ONLY when BEGIN_MARKER is absent (see findManagedRegion), so -1
// disables the clamp for marker-less files without a redundant scan.
const fenceStart = region ? region.start : -1;
const clampEnd = (start: number, end: number): number =>
fenceStart >= 0 && start < fenceStart ? Math.min(end, fenceStart) : end;
// Collect every table header first: a table body runs to the NEXT header, whatever it is.
const headers = analyzeTomlStructure(content).headers;
// [model_providers.<id>] tables outside the fence, folded with their own sub-tables (see
// the function doc). A table passing the predicate (our api_key literal + a loopback
// base_url + the durable marker inline or in a re-serialized child) contributes to
// `ownedProviderIds` for the model scan below; one with OUR id is additionally swept as
// an orphan of a previous managed block (a leftover here collides with the regenerated
// block's provider table — duplicate key — and alias rewriting skips provider orphans
// because they have no alias and no model id). The dot-terminated prefix keeps a user's
// `[model_providers.opencodex_backup]` out of scope.
const ownedProviderIds = new Set<string>();
for (const [position, header] of headers.entries()) {
if (header.array || header.segments.length !== 2 || header.segments[0] !== "model_providers") continue;
// Inside the fence the regular splice owns the table, but it is still ownership
// evidence: models kept outside the fence after a Grok rewrite (retired ids) inherit
// their verdict from the fenced provider, so classification must happen while the
// fence still exists or teardown leaves them with a dangling model_provider reference.
const insideRegion = region !== null
&& header.index >= region.start && header.index < region.end;
const end = clampEnd(header.index, headers[position + 1]?.index ?? content.length);
let body = content.slice(header.index + header.length, end);
// Re-serialized children may sit non-contiguously (a user table can interleave), so
// fold every same-provider descendant globally, like the model scan below, and remove
// them by their exact ranges. Never fold across the fence: a pre-fence parent must
// judge on pre-fence bytes only, and fenced or below-fence content is not the orphan's.
const additionalRanges: Array<{ start: number; end: number }> = [];
for (let next = 0; next < headers.length; next += 1) {
if (next === position) continue;
const child = headers[next]!;
if (region && child.index >= region.start && child.index < region.end) continue;
if (fenceStart >= 0
&& (header.index < fenceStart) !== (child.index < fenceStart)) continue;
if (child.segments.length <= 2
|| child.segments[0] !== "model_providers"
|| child.segments[1] !== header.segments[1]) continue;
const childEnd = clampEnd(child.index, headers[next + 1]?.index ?? content.length);
body += "\n" + content.slice(child.index + child.length, childEnd);
additionalRanges.push({ start: child.index, end: childEnd });
}
const keys = tableBodyKeys(body);
if (keys.get("api_key") !== OPENCODEX_API_KEY) continue;
if (!isLoopbackBaseUrl(keys.get("base_url"))) continue;
// The durable marker may sit inline on the provider, or be promoted by Grok's
// re-serializer into `[model_providers.<id>.extra_headers]` — where the folded body
// shows it as a bare `x-opencodex-grok = "1"` assignment. Both forms decide.
if (!hasInlineOwnershipMarker(keys.get("extra_headers"))
&& keys.get(OPENCODEX_GROK_MARKER) !== "1") continue;
ownedProviderIds.add(header.segments[1]!);
if (insideRegion) continue;
if (header.segments[1] === OPENCODEX_PROVIDER_ID) {
orphans.push({
alias: "",
modelId: "",
ownership: "explicit",
start: header.index,
end,
additionalRanges,
});
}
}
for (const [position, header] of headers.entries()) {
if (header.array || header.segments.length !== 2 || header.segments[0] !== "model") continue;
// Inside the fence the regular splice already owns it.
if (region && header.index >= region.start && header.index < region.end) continue;
const bodyEnd = clampEnd(header.index, headers[position + 1]?.index ?? content.length);
const keys = tableBodyKeys(content.slice(header.index + header.length, bodyEnd));
const modelId = keys.get("model");
if (!modelId) continue;
// Two shapes carry our ownership signal. The current managed block routes every model
// through a shared provider table (`model_provider = "opencodex"`), so a re-serialized
// unfenced entry has NO api_key/base_url of its own — the evidence lives on the provider
// table it references (Codex-side precedent: classifyCodexRouting follows model_provider
// for the same reason). Inheritance is accepted only from a provider that itself passed
// the strict predicate above, and only for rows whose alias carries the generated
// fingerprint: a user is free to reference the managed provider from their own
// [model.*] table, and inheritance alone must not grant removal authority over it.
const providerId = keys.get("model_provider");
const inheritedOwned =
providerId === OPENCODEX_PROVIDER_ID
&& ownedProviderIds.has(OPENCODEX_PROVIDER_ID)
&& isGeneratedAliasForModel(header.segments[1]!, modelId);
if (!inheritedOwned) {
if (keys.get("api_key") !== OPENCODEX_API_KEY) continue;
if (!isLoopbackBaseUrl(keys.get("base_url"))) continue;
}
let hasOwnershipMarker = hasInlineOwnershipMarker(keys.get("extra_headers"));
// Swallow the entry's OWN sub-tables (`[model.<alias>.extra_headers]`, and after #1756
// `[[model.<alias>.reasoning_efforts]]`). Grok may re-serialize them non-contiguously,
// so collect exact descendant spans globally rather than stopping at the first
// unrelated table.
const additionalRanges: Array<{ start: number; end: number }> = [];
for (let next = 0; next < headers.length; next += 1) {
if (next === position) continue;
const child = headers[next]!;
if (region && child.index >= region.start && child.index < region.end) continue;
if (child.segments.length <= 2
|| child.segments[0] !== "model"
|| child.segments[1] !== header.segments[1]) continue;
const childEnd = clampEnd(child.index, headers[next + 1]?.index ?? content.length);
additionalRanges.push({ start: child.index, end: childEnd });
if (!child.array && child.segments.length === 3 && child.segments[2] === "extra_headers") {
const childKeys = tableBodyKeys(content.slice(child.index + child.length, childEnd));
if (childKeys.get(OPENCODEX_GROK_MARKER) === "1") hasOwnershipMarker = true;
}
}
const legacyGenerated = isLegacyGeneratedTable(header.segments[1]!, keys);
// An inherited model has no per-model marker; its verdict comes from the provider
// table it references, which only lands here when that provider proved durable
// ownership. A legacy-fingerprint model keeps dev's conservative classification.
const ownership: "explicit" | "legacy" = inheritedOwned || hasOwnershipMarker
? "explicit"
: "legacy";
if (!hasOwnershipMarker && !legacyGenerated && !inheritedOwned) continue;
orphans.push({
alias: header.segments[1]!,
modelId,
ownership,
start: header.index,
end: bodyEnd,
additionalRanges,
});
}
return orphans;
}
function orphanRanges(orphans: readonly OrphanTable[]): Array<{ start: number; end: number }> {
const unique = new Map<string, { start: number; end: number }>();
for (const orphan of orphans) {
for (const range of [{ start: orphan.start, end: orphan.end }, ...orphan.additionalRanges]) {
unique.set(`${range.start}:${range.end}`, range);
}
}
return [...unique.values()];
}
/** Remove exact whole-table ranges, back to front so earlier offsets stay valid. */
function removeTableRanges(content: string, ranges: readonly { start: number; end: number }[]): string {
let next = content;
const unique = new Map(ranges.map(range => [`${range.start}:${range.end}`, range]));
for (const range of [...unique.values()].sort((a, b) => b.start - a.start)) {
next = next.slice(0, range.start) + next.slice(range.end);
}
return next;
}
function removeOrphanTables(content: string, orphans: OrphanTable[]): string {
return removeTableRanges(content, orphanRanges(orphans));
}
/** Model aliases and routed ids owned by one complete managed region. */
function managedModelAliases(content: string, region: ManagedRegion | null): Map<string, string> {
const models = new Map<string, string>();
if (!region) return models;
const structure = analyzeTomlStructure(content);
for (const [position, header] of structure.headers.entries()) {
if (header.array || header.segments.length !== 2 || header.segments[0] !== "model") continue;
if (header.index < region.start || header.index >= region.end) continue;
const bodyEnd = Math.min(structure.headers[position + 1]?.index ?? content.length, region.end);
const modelId = tableBodyKeys(content.slice(header.index + header.length, bodyEnd)).get("model");
if (modelId !== undefined) models.set(header.segments[1]!, modelId);
}
return models;
}
/** Read one exact path from an already parsed TOML document. */
type TomlPathSegment = string | number;
function tomlPathString(document: unknown, path: readonly TomlPathSegment[]): string | null {
let value = document;
for (const segment of path) {
if (typeof segment === "number") {
if (!Array.isArray(value)) return null;
value = value[segment];
} else {
if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
value = (value as Record<string, unknown>)[segment];
}
}
return typeof value === "string" ? value : null;
}
/** Parse a probe document and read one exact semantic path. */
function parsedTomlPathString(content: string, path: readonly TomlPathSegment[]): string | null {
try {
return tomlPathString(Bun.TOML.parse(content), path);
} catch {
return null;
}
}
type ModelReferencePatternSegment = string | "*";
interface ModelReferencePath {
path: readonly ModelReferencePatternSegment[];
/** A structured reference assignment that can be removed whole without losing sibling config. */
removableContainerPath?: readonly string[];
}
/** Grok config values whose strings resolve through the `[model.<alias>]` catalog. */
const MODEL_REFERENCE_PATHS: readonly ModelReferencePath[] = [
{ path: ["models", "default"] },
{ path: ["models", "web_search"] },
{ path: ["models", "session_summary"] },
{ path: ["models", "image_description"] },
{ path: ["models", "prompt_suggestion"] },
{ path: ["ui", "fork_secondary_model"] },
{ path: ["subagents", "models", "*"] },
{ path: ["subagents", "roles", "*", "model"] },
{ path: ["subagents", "personas", "*", "model"] },
{ path: ["auto_mode", "classifier_model"] },
{
path: ["goal", "planner_model", "model"],
removableContainerPath: ["goal", "planner_model"],
},
{
path: ["goal", "strategist_model", "model"],
removableContainerPath: ["goal", "strategist_model"],
},
{
path: ["goal", "skeptic_models", "*", "model"],
removableContainerPath: ["goal", "skeptic_models"],
},
];
interface AliasReference {
path: TomlPathSegment[];
alias: string;
removableContainerPath?: readonly string[];
}
function collectAliasReferences(document: unknown): AliasReference[] {
const references: AliasReference[] = [];
const visit = (
value: unknown,
pattern: readonly ModelReferencePatternSegment[],
patternIndex: number,
path: TomlPathSegment[],
removableContainerPath: readonly string[] | undefined,
): void => {
if (patternIndex === pattern.length) {
if (typeof value === "string") {
references.push({
path,
alias: value,
...(removableContainerPath ? { removableContainerPath } : {}),
});
}
return;
}
const segment = pattern[patternIndex]!;
if (segment === "*") {
if (Array.isArray(value)) {
for (const [index, item] of value.entries()) {
visit(item, pattern, patternIndex + 1, [...path, index], removableContainerPath);
}
} else if (typeof value === "object" && value !== null) {
for (const [key, item] of Object.entries(value)) {
visit(item, pattern, patternIndex + 1, [...path, key], removableContainerPath);
}
}
return;
}
if (typeof value !== "object" || value === null || Array.isArray(value)) return;
visit(
(value as Record<string, unknown>)[segment],
pattern,
patternIndex + 1,
[...path, segment],
removableContainerPath,
);
};
for (const reference of MODEL_REFERENCE_PATHS) {
visit(document, reference.path, 0, [], reference.removableContainerPath);
}
return references;
}
function sourcePath(path: readonly TomlPathSegment[]): string[] {
return path.filter((segment): segment is string => typeof segment === "string");
}
function pathsEqual(left: readonly string[], right: readonly string[]): boolean {
return left.length === right.length && left.every((segment, index) => segment === right[index]);
}
function pathStartsWith(path: readonly string[], prefix: readonly string[]): boolean {
return path.length >= prefix.length
&& prefix.every((segment, index) => segment === path[index]);
}
function tomlContainerStringSpans(
content: string,
start: number,
end: number,
): Array<{ start: number; end: number }> {
const spans: Array<{ start: number; end: number }> = [];
for (let index = start + 1; index < end - 1;) {
const char = content[index]!;
if (char === "#") {
const newline = content.indexOf("\n", index);
index = newline === -1 || newline >= end ? end : newline + 1;
continue;
}
if (char === '"' || char === "'") {
const span = tomlStringSpanAt(content, index);
if (span === null || span.end > end) return [];
spans.push({ start: index, end: span.end });
index = span.end;
continue;
}
index += 1;
}
return spans;
}
interface AliasReferenceCandidate {
valueStart: number;
valueEnd: number;
assignmentPath: string[];
directLine: { start: number; end: number } | null;
containerLine: { start: number; end: number } | null;
}
/** Rename or remove every declared semantic model reference without touching user prose. */
function transformAliasReferences(
content: string,
replacements: ReadonlyMap<string, string | null>,
allowRootDotted = true,
): string {
if (replacements.size === 0) return content;
let document: unknown;
try {
document = Bun.TOML.parse(content);
} catch {
throw new Error(
"Grok config rewrite refused: Bun could not parse the TOML document safely.",
);
}
const references = collectAliasReferences(document);
const targets = references.filter(reference => replacements.has(reference.alias));
if (targets.length === 0) return content;
const structure = analyzeTomlStructure(content);
const edits: Array<{ start: number; end: number; replacement: string }> = [];
const candidates: AliasReferenceCandidate[] = [];
const assignment = new RegExp(String.raw`^([ \t]*(${DOTTED_KEY})[ \t]*=)`, "gm");
let headerPosition = -1;
for (const match of structure.view.matchAll(assignment)) {
const assignmentStart = match.index!;
if (!structure.containerRootLineStarts.has(assignmentStart)) continue;
while ((structure.headers[headerPosition + 1]?.index ?? Number.POSITIVE_INFINITY)
< assignmentStart) headerPosition += 1;
const currentHeader = headerPosition >= 0 ? structure.headers[headerPosition]! : null;
if (!allowRootDotted && currentHeader === null) continue;
const segments = canonicalDottedKey(match[2]!);
const assignmentPath = [...(currentHeader?.segments ?? []), ...segments];
let valueStart = assignmentStart + match[1]!.length;
while (content[valueStart] === " " || content[valueStart] === "\t") valueStart += 1;
const directTargets = targets.filter(target => pathsEqual(sourcePath(target.path), assignmentPath));
if (directTargets.length > 0) {
const value = tomlStringSpanAt(content, valueStart);
if (value !== null) {
const suffix = /^[ \t]*(?:#[^\r\n]*)?(?:\r?\n|$)/.exec(content.slice(value.end));
if (suffix !== null) {
candidates.push({
valueStart,
valueEnd: value.end,
assignmentPath,
directLine: { start: assignmentStart, end: value.end + suffix[0].length },
containerLine: null,
});
continue;
}
}
}
const containerTargets = targets.filter(target =>
pathStartsWith(sourcePath(target.path), assignmentPath));
if (containerTargets.length === 0 || (content[valueStart] !== "{" && content[valueStart] !== "[")) continue;
const containerEnd = tomlContainerEnd(content, valueStart);
if (containerEnd === null) continue;
const suffix = /^[ \t]*(?:#[^\r\n]*)?(?:\r?\n|$)/.exec(content.slice(containerEnd));
if (suffix === null) continue;
const containerLine = { start: assignmentStart, end: containerEnd + suffix[0].length };
for (const value of tomlContainerStringSpans(content, valueStart, containerEnd)) {
candidates.push({
valueStart: value.start,
valueEnd: value.end,
assignmentPath,
directLine: null,
containerLine,
});
}
}
for (const [targetIndex, target] of targets.entries()) {
const replacement = replacements.get(target.alias)!;
const targetSourcePath = sourcePath(target.path);
const probeCandidates = candidates.filter(candidate =>
pathsEqual(candidate.assignmentPath, targetSourcePath)
|| pathStartsWith(targetSourcePath, candidate.assignmentPath));
if (probeCandidates.length === 0 && !allowRootDotted) continue;
if (probeCandidates.length === 0 || probeCandidates.length > 128) {
throw new Error(
"Grok config rewrite refused: the model-reference source could not be bounded safely.",
);
}
let located = false;
for (const candidate of probeCandidates) {
let sentinel = `__opencodex_reference_probe_${targetIndex}_${candidate.valueStart}__`;
while (sentinel === target.alias) sentinel += "_";
const probe = content.slice(0, candidate.valueStart)
+ tomlString(sentinel)
+ content.slice(candidate.valueEnd);
if (parsedTomlPathString(probe, target.path) !== sentinel) continue;
if (replacement === null) {
let removal = candidate.directLine;
if (removal === null && candidate.containerLine !== null
&& target.removableContainerPath
&& pathsEqual(candidate.assignmentPath, target.removableContainerPath)) {
const containerReferences = references.filter(reference =>
pathStartsWith(sourcePath(reference.path), candidate.assignmentPath));
if (containerReferences.length > 0
&& containerReferences.every(reference => replacements.get(reference.alias) === null)) {
removal = candidate.containerLine;
}
}
if (removal === null) {
throw new Error(
"Grok teardown refused: a model reference uses an inline TOML shape that cannot "
+ "be removed without rewriting user-owned bytes.",
);
}
edits.push({ start: removal.start, end: removal.end, replacement: "" });
} else {
edits.push({
start: candidate.valueStart,
end: candidate.valueEnd,
replacement: tomlString(replacement),
});
}
located = true;
break;
}
if (!located) {
throw new Error(
"Grok config rewrite refused: the semantic model reference could not be located safely.",
);
}
}
let next = content;
const uniqueEdits = new Map(edits.map(edit => [`${edit.start}:${edit.end}:${edit.replacement}`, edit]));
for (const edit of [...uniqueEdits.values()].sort((a, b) => b.start - a.start)) {
next = next.slice(0, edit.start) + edit.replacement + next.slice(edit.end);
}
return next;
}
/** Repoint references at whichever alias survived orphan adoption, or remove them. */
function rewriteAliasReferences(content: string, replacements: Map<string, string | null>): string {
return transformAliasReferences(content, replacements);
}
/** Remove only references that name model aliases teardown actually swept. */
function removeAliasReferences(
content: string,
removedAliases: ReadonlySet<string>,
allowRootDotted = true,
): string {
return transformAliasReferences(
content,
new Map([...removedAliases].map(alias => [alias, null] as const)),
allowRootDotted,
);
}
function orphanedMarkerResult(action: string): GrokInjectResult {
return {
ok: false,
changed: false,
message: `Grok config ${action} refused: found the opencodex begin marker without its end marker. `
+ "The managed region boundary is ambiguous, so nothing was modified. "
+ "Repair ~/.grok/config.toml manually (see config.toml.bak-opencodex) and re-run.",
skippedReason: "orphaned-marker",
};
}
function copyBackupOnce(configPath: string, backupPath: string): void {
if (existsSync(backupPath)) return;
try {
copyFileSync(configPath, backupPath, constants.COPYFILE_EXCL);
} catch (error) {
if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
}
}
function errorResult(action: string, error: unknown): GrokInjectResult {
const detail = error instanceof Error ? error.message : String(error);
return { ok: false, changed: false, message: `Could not ${action} Grok config: ${detail}` };
}
export function buildGrokManagedBlock(
port: number,
models: GrokInjectModel[],
hostname?: string,
reservedAliases?: ReadonlySet<string>,
/**
* Ids to allocate an alias for but NOT emit. Alias numbering must not depend on which
* models the user switched off, or excluding one colliding model would rename another
* model's alias out from under a grok config that already uses it.
*/
excluded?: ReadonlySet<string>,
): string {
const host = providerBaseHost(hostname);
const baseUrl = `http://${host}:${port}/v1`;
const lines = [
BEGIN_MARKER,
"",
`[model_providers.${OPENCODEX_PROVIDER_ID}]`,
`base_url = ${tomlString(baseUrl)}`,
'api_backend = "responses"',
'api_key = "opencodex-loopback"',
// Best-effort attribution tag for the usage dashboard. Upstream Grok sends
// extra_headers verbatim on inference calls (11-custom-models.md). This is NOT a
// security boundary — any loopback client could send the same header.
'extra_headers = { "x-opencodex-grok" = "1" }',
];
const aliasCounts = new Map<string, number>();
const taken = new Set(reservedAliases ?? []);
for (const model of models) {
const baseAlias = `ocx-${model.id.replace(/[^A-Za-z0-9_-]/g, "-")}`;
let count = (aliasCounts.get(baseAlias) ?? 0) + 1;
let alias = count === 1 ? baseAlias : `${baseAlias}-${count}`;
// User-owned [model.<alias>] tables outside the fence are reserved: emitting a
// duplicate table header would make the whole TOML invalid for grok.
while (taken.has(alias)) {
count += 1;
alias = `${baseAlias}-${count}`;
}
aliasCounts.set(baseAlias, count);
taken.add(alias);
// Slot consumed, table not written: this is what keeps every other alias stable
// across selection changes.
if (excluded?.has(model.id)) continue;
lines.push(
"",
`[model.${alias}]`,
`model = ${tomlString(model.id)}`,
`model_provider = ${tomlString(OPENCODEX_PROVIDER_ID)}`,
`name = ${tomlString(model.name ?? `OCX ${model.id}`)}`,
);
if (Number.isFinite(model.contextWindow) && (model.contextWindow ?? 0) > 0) {
lines.push(`context_window = ${model.contextWindow}`);
}
// Array-of-tables MUST follow every parent keyval (including inline extra_headers).
// Keep every picker option inside Grok's accepted CLI vocabulary; ultra is Codex-only.
const efforts = sanitizeGrokReasoningEfforts(model.reasoningEfforts);
const defaultEffort = grokDefaultReasoningEffort(efforts, model.defaultReasoningEffort);
if (defaultEffort !== undefined) {
lines.push(
"supports_reasoning_effort = true",
`reasoning_effort = ${tomlString(defaultEffort)}`,
);
for (const effort of efforts) {
const option = grokReasoningEffortOption(effort, effort === defaultEffort);
lines.push(
"",
`[[model.${alias}.reasoning_efforts]]`,
`id = ${tomlString(option.id)}`,
`value = ${tomlString(option.value)}`,
`label = ${tomlString(option.label)}`,
`description = ${tomlString(option.description)}`,
`default = ${option.default}`,
);
}
}
}
lines.push(END_MARKER);
return lines.join("\n");
}
export function injectGrokConfig(
port: number,
models: GrokInjectModel[],
opts: {
grokHome?: string;
hostname?: string;
excluded?: ReadonlySet<string>;
/** Unfiltered known ids used only to distinguish hidden current models from retired ones. */
catalogModelIds?: ReadonlySet<string>;
/** Canonical provider keys disabled in config and therefore absent from catalog fetching. */
disabledProviderNamespaces?: ReadonlySet<string>;
/** Configured combo public ids that may syntactically resemble provider/model ids. */
comboPublicModelIds?: ReadonlySet<string>;
} = {},
): GrokInjectResult {
const grokHome = resolveGrokHome(opts.grokHome);
if (!isDirectory(grokHome)) {
return {
ok: true,
changed: false,
message: `Grok home not found at ${grokHome}; config injection skipped.`,
skippedReason: "no-grok-home",
};
}
// Non-loopback binds require the real admission token (src/server/auth-cors.ts), and there is
// no safe way for a REGENERATED block to carry it: a literal token would write the user's
// secret into their own file and overwrite it on every start/ensure/restart, while omitting
// api_key in favour of env_key opens grok's credential fallthrough — with no `model_provider`
// to fail closed, an unresolved env_key makes grok send its xAI session bearer to our
// plaintext LAN endpoint (upstream config.rs resolve_credentials). So we do not auto-register
// at all here; the user configures models manually, outside our fence, where nothing we do
// can clobber their credential.
if (!isLoopbackHostname(opts.hostname)) {
const removed = stripGrokConfig({ ...(opts.grokHome !== undefined ? { grokHome: opts.grokHome } : {}) });
const cleanup = removed.changed
? " Removed the previously generated block, which pointed at a loopback address."
: "";
return {
ok: true, // a deliberate policy skip, not a failure — it must never block startup
changed: removed.changed,
skippedReason: "non-loopback",
message: `Grok auto-registration skipped: opencodex is bound to the non-loopback host `
+ `"${opts.hostname}", where requests need your admission token. A managed block would `
+ `either store that secret in ~/.grok/config.toml or overwrite it on the next start, so `
+ `add the models yourself OUTSIDE the opencodex markers (see the Grok Build guide).${cleanup}`,
};
}
const configPath = join(grokHome, "config.toml");
const backupPath = join(grokHome, "config.toml.bak-opencodex");
try {
const configExisted = existsSync(configPath);
const rawContent = configExisted ? readFileSync(configPath, "utf8") : "";
const eol = dominantEol(rawContent);
const originalContent = applyEol(rawContent, "\n");
const originalRegion = findManagedRegion(originalContent);
// Ambiguous fence: refuse before the sweep, or "outside the region" could mean the
// entire file.
if (originalRegion?.orphaned) return orphanedMarkerResult("injection");
const previousManagedModels = managedModelAliases(originalContent, originalRegion);
// Adopt our own pre-fence entries (#511) BEFORE reserving user aliases, so the stale
// duplicate is replaced instead of routed around forever. Runs inside the normalized
// window so the user's dominant EOL is still restored below.
// Durably marked rows use the full UNFILTERED catalog: explicitly excluded and otherwise
// hidden current models must still lose stale generated tables. Ambiguous pre-marker legacy
// rows are migrated only when this write emits their replacement. Direct callers that do not
// have a separate catalog keep the historical `models` behavior.
const catalogModelIds = opts.catalogModelIds ?? new Set(models.map(model => model.id));
const emittedModelIds = new Set(models
.filter(model => !opts.excluded?.has(model.id))
.map(model => model.id));
const orphans = findOpencodexOrphans(originalContent, originalRegion)
.filter(orphan =>
// A provider table carries no alias and no model id: its strict predicate (our key
// + loopback + durable marker) is itself the deletion authority, and a leftover
// collides with the regenerated provider table (duplicate key).
orphan.alias === ""
|| (orphan.ownership === "legacy"
// A legacy fingerprint is not durable deletion authority. Migrate it only when this
// same write will replace the row with a marked managed table.
? emittedModelIds.has(orphan.modelId)
: catalogModelIds.has(orphan.modelId)
|| isDisabledProviderModelId(
orphan.modelId,
opts.disabledProviderNamespaces,
opts.comboPublicModelIds,
)));
const content = removeOrphanTables(originalContent, orphans);
// Removing bytes above the fence MOVES it: recompute rather than adjust arithmetic,
// so the splice below cannot cut the file in the wrong place.
const region = orphans.length > 0 ? findManagedRegion(content) : originalRegion;
const buildCandidate = (reservedAliases: ReadonlySet<string>): string => {
const block = buildGrokManagedBlock(port, models, opts.hostname, reservedAliases, opts.excluded);
let candidate: string;
if (region) {
candidate = content.slice(0, region.start) + block + content.slice(region.end);
} else if (content.length === 0) {
candidate = `${block}\n`;
} else {
// One separator newline preserves the user's original terminator for stripping.
candidate = `${content}\n${block}\n`;
}
// Repoint selectors after allocation, so parsing below checks the actual write bytes.
const nextManagedModels = managedModelAliases(candidate, findManagedRegion(candidate));
const survivors = new Map<string, string>();
for (const [alias, modelId] of nextManagedModels) {
if (!survivors.has(modelId)) survivors.set(modelId, alias);
}
const replacements = new Map<string, string | null>();
for (const removed of [
...orphans.filter(orphan => orphan.alias !== "")
.map(orphan => ({ alias: orphan.alias, modelId: orphan.modelId })),
...[...previousManagedModels].map(([alias, modelId]) => ({ alias, modelId })),
]) {
if (nextManagedModels.get(removed.alias) === removed.modelId) continue;
const replacement = survivors.get(removed.modelId) ?? null;
if (replacement !== removed.alias) replacements.set(removed.alias, replacement);
}
return rewriteAliasReferences(candidate, replacements);
};
const userContent = region ? content.slice(0, region.start) + content.slice(region.end) : content;
let userContentValid = false;
try {
Bun.TOML.parse(userContent);
userContentValid = true;
} catch {
// Preserve the old, conservative reservation and write behavior for malformed user TOML.
}
let nextContent: string;
if (!userContentValid) {
nextContent = buildCandidate(userModelAliases(content, region, true));
} else {
const validCandidate = (includeNested: boolean): string | null => {
let candidate: string;
try {
candidate = buildCandidate(userModelAliases(content, region, includeNested));
} catch (error) {
if (error instanceof Error && error.message === "Grok config rewrite refused: Bun could not parse the TOML document safely.") return null;
throw error;
}
try {
Bun.TOML.parse(applyEol(candidate, eol));
return candidate;
} catch {
return null;
}
};
nextContent = validCandidate(false) ?? validCandidate(true) ?? "";
if (nextContent === "") {
throw new Error("Grok config injection refused: neither alias choice produced valid TOML after model-reference rewriting.");
}
}
const output = applyEol(nextContent, eol);
if (output === rawContent) {
return { ok: true, changed: false, message: "Grok config already contains the current opencodex managed block." };
}
// Back up before a first-time fence write AND before any sweep, since adopting an orphan
// deletes a table the user has in their file. Previously the adjacent-orphan layout got a
// backup only as a side effect of the fence being destroyed (which made `region` falsy);
// preserving the fence must not silently drop that safety net.
if (configExisted && (!region || orphans.length > 0)) copyBackupOnce(configPath, backupPath);
atomicWriteFile(configPath, output);
return {
ok: true,
changed: true,
message: region
? "Updated the opencodex managed block in Grok config."
: "Added the opencodex managed block to Grok config.",
};
} catch (error) {
return errorResult("inject", error);
}
}
export function stripGrokConfig(opts: { grokHome?: string } = {}): GrokInjectResult {
const grokHome = resolveGrokHome(opts.grokHome);
if (!isDirectory(grokHome)) {
return {
ok: true,
changed: false,
message: `Grok home not found at ${grokHome}; no managed config to remove.`,
skippedReason: "no-grok-home",
};
}
const configPath = join(grokHome, "config.toml");
if (!existsSync(configPath)) {
return { ok: true, changed: false, message: "Grok config not found; no managed block to remove." };
}
try {
const rawContent = readFileSync(configPath, "utf8");
const eol = dominantEol(rawContent);
const content = applyEol(rawContent, "\n");
const originalRegion = findManagedRegion(content);
if (originalRegion?.orphaned) return orphanedMarkerResult("cleanup");
// Remove the fence against its ORIGINAL offsets first. A pre-fence orphan's span is clamped
// at the fence start and can include the separator newline injection added. Sweeping that
// orphan first and then applying this separator undo would remove one additional USER newline.
let stripped: string;
let orphanCount = 0;
if (originalRegion) {
const fullOrphans = findOpencodexOrphans(content, originalRegion)
.filter(orphan => orphan.ownership === "explicit");
let removalEnd = originalRegion.end;
if (content.startsWith("\n", removalEnd)) removalEnd += 1;
let prefix = content.slice(0, originalRegion.start);
const restOfFile = content.slice(removalEnd);
// Undo the single separator newline injection added. Two cases, mirroring inject:
// "X\n" -> "X\n" + "\n" + block => prefix ends "\n\n", drop one.
// "X" -> "X" + "\n" + block => prefix ends "\n" at EOF, drop it.
// A block the user has appended content after is left alone: we never shrink their bytes.
if (prefix.endsWith("\n\n")) prefix = prefix.slice(0, -1);
else if (restOfFile.length === 0 && prefix.endsWith("\n")) prefix = prefix.slice(0, -1);
// Keep the old fence boundary while sweeping. Concatenating first would let the last
// pre-fence orphan absorb comment-only or bare-key user content appended after the fence.
const prefixOrphans = findOpencodexOrphans(prefix, null)
.filter(orphan => orphan.ownership === "explicit");
const tailOrphans = findOpencodexOrphans(restOfFile, null)
.filter(orphan => orphan.ownership === "explicit");
const removedAliases = new Set(
[...fullOrphans, ...prefixOrphans, ...tailOrphans]
.map(orphan => orphan.alias)
// Provider orphans carry no alias; their ranges above already removed the table.
.filter(alias => alias !== ""),
);
// The backup must cover every removed TABLE, not just aliased rows: provider-only
// orphans carry no alias and would otherwise be swept without any backup.
orphanCount = new Set(
[...fullOrphans, ...prefixOrphans, ...tailOrphans]
.flatMap(orphan => orphanRanges([orphan])),
).size;
const fullRanges = orphanRanges(fullOrphans);
const prefixRanges = [
...orphanRanges(prefixOrphans),
...fullRanges.filter(range => range.end <= originalRegion.start),
];
const tailRanges = [
...orphanRanges(tailOrphans),
...fullRanges
.filter(range => range.start >= removalEnd)
.map(range => ({ start: range.start - removalEnd, end: range.end - removalEnd })),
];
// Preserve the original fence as a structural boundary while cleaning references too.
// Joining first can re-parent a headerless tail under the last table in `prefix`.
stripped = removeAliasReferences(
removeTableRanges(prefix, prefixRanges),
removedAliases,
) + removeAliasReferences(
removeTableRanges(restOfFile, tailRanges),
removedAliases,
false,
);
} else {
// Retired or otherwise non-emitted OpenCodex tables may intentionally remain outside the
// fence while the integration is enabled. Teardown owns those strictly identified tables
// even after Grok has re-serialized the file and dropped our marker comments.
const orphans = findOpencodexOrphans(content, null)
.filter(orphan => orphan.ownership === "explicit");
if (orphans.length === 0) {
return { ok: true, changed: false, message: "No opencodex managed block found in Grok config." };
}
orphanCount = orphans.length;
stripped = removeOrphanTables(content, orphans);
stripped = removeAliasReferences(
stripped,
new Set(orphans.map(orphan => orphan.alias).filter(alias => alias !== "")),
);
}
if (orphanCount > 0) copyBackupOnce(configPath, join(grokHome, "config.toml.bak-opencodex"));
atomicWriteFile(configPath, applyEol(stripped, eol));
return {
ok: true,
changed: true,
message: originalRegion
? "Removed the opencodex managed block from Grok config."
: "Removed stale opencodex-managed model entries from Grok config.",
};
} catch (error) {
return errorResult("strip", error);
}
}
/** Decode a TOML basic-string body: JSON-compatible escapes plus TOML's \uXXXX / \UXXXXXXXX. */
function decodeTomlBasicString(body: string): string {
return body.replace(
/\\(u[0-9A-Fa-f]{4}|U[0-9A-Fa-f]{8}|.)/g,
(whole, esc: string) => {
if (esc[0] === "u") return String.fromCharCode(parseInt(esc.slice(1), 16));
if (esc[0] === "U") {
const code = parseInt(esc.slice(1), 16);
return code <= 0x10ffff ? String.fromCodePoint(code) : whole;
}
switch (esc) {
case "b": return "\b";
case "t": return "\t";
case "n": return "\n";
case "f": return "\f";
case "r": return "\r";
case '"': return '"';
case "\\": return "\\";
default: return whole; // invalid escape — keep raw, reservation stays conservative
}
},
);
}