@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
202 lines (185 loc) • 11 kB
text/typescript
/**
* Standalone native originals for a linked Child.
*
* A Child applying its Home's route intent writes the Child's own native switches
* (clientIntegrations.codex|grok|claude-desktop, claudeCode.enabled, and as side effects
* claudeCode.authModeMigratedAt and apiSurfaces.messages). This private, machine-scoped
* record remembers, per field, the value that existed before route intent first changed it
* (absent is a value: null), plus the last value this writer published and any value it was
* about to publish (pending). It is captured once and never overwritten by later syncs or
* connects, and it is not bound to a link: it means "the standalone value before route intent
* touched it", which stays true after a crashed connect followed by a different link.
*
* Callers hold the client lifecycle lock; every function here takes the config mutation lock,
* preserving the documented lifecycle -> config order. Writes are write-ahead: the original and
* pending value reach this file before the atomic config write, and the value is marked
* published after it. Restore (disconnect, failed enrollment) puts the original back only for a
* field whose current value this writer published or had pending; any other value is the
* person's own edit and is kept. The record is removed only after the restored config is read
* back and verified, so an interrupted restore is retried safely by the next disconnect.
*
* Limit (ABA): a person who sets a field to exactly the value this writer published cannot be
* told apart from the writer, and that field is restored. The Child's local opt-out list is the
* person's own choice and is not part of this record.
*/
import { chmodSync, lstatSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
import { join } from "node:path";
import { atomicWriteFile, isMissingPathError } from "../config/atomic-write";
import { withConfigMutationLockSync } from "../config/mutation-lock";
import { mutatePersistedConfig, readConfigForAdmittedMutation } from "../config/persisted-mutation";
import { deleteConfigObjectChildKey } from "../config/rebase-provenance";
import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
import { hardenSecretDir } from "../lib/windows-secret-acl";
import { linkDir } from "../link/paths";
import type { OcxConfig } from "../types";
export const NATIVE_INTENT_FIELDS = ["codex", "grok", "claude-desktop", "claude", "claudeMigratedAt", "messages"] as const;
export type NativeIntentField = typeof NATIVE_INTENT_FIELDS[number];
/** null means the key is absent; anything else is the exact persisted value. */
export type NativeIntentSlot = boolean | string | Record<string, unknown> | null;
export type NativeIntentFields = Record<NativeIntentField, NativeIntentSlot>;
type Entry = { original: NativeIntentSlot; published?: NativeIntentSlot; pending?: NativeIntentSlot };
export type NativeIntentOriginals = { version: 1; fields: Partial<Record<NativeIntentField, Entry>> };
const RECORD_MAX_BYTES = 16 * 1024;
const unsafe = (): never => {
throw new Error(`Native intent originals record is unreadable; inspect or remove ${nativeIntentOriginalsPath()} and retry`);
};
const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
const sameSlot = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
export function nativeIntentOriginalsPath(): string { return join(linkDir(), "native-intent-originals.json"); }
const integrationField = (field: NativeIntentField): field is "codex" | "grok" | "claude-desktop" =>
field === "codex" || field === "grok" || field === "claude-desktop";
const parentKey = (field: NativeIntentField) => integrationField(field) ? "clientIntegrations" as const
: field === "messages" ? "apiSurfaces" as const : "claudeCode" as const;
const childKey = (field: NativeIntentField): string => integrationField(field) ? field
: field === "messages" ? "messages" : field === "claude" ? "enabled" : "authModeMigratedAt";
export function readNativeIntentField(config: OcxConfig, field: NativeIntentField): NativeIntentSlot {
const parent = (config as unknown as Record<string, unknown>)[parentKey(field)];
if (!isRecord(parent) || !Object.hasOwn(parent, childKey(field)) || parent[childKey(field)] === undefined) return null;
return structuredClone(parent[childKey(field)]) as NativeIntentSlot;
}
export function nativeIntentFields(config: OcxConfig): NativeIntentFields {
return Object.fromEntries(NATIVE_INTENT_FIELDS.map(field => [field, readNativeIntentField(config, field)])) as NativeIntentFields;
}
function writeNativeIntentField(config: OcxConfig, field: NativeIntentField, value: NativeIntentSlot): void {
const key = parentKey(field);
if (value === null) { deleteConfigObjectChildKey(config, key, childKey(field)); return; }
const record = config as unknown as Record<string, unknown>;
const parent = isRecord(record[key]) ? record[key] as Record<string, unknown> : {};
record[key] = { ...parent, [childKey(field)]: structuredClone(value) };
}
function validSlot(field: NativeIntentField, value: unknown): value is NativeIntentSlot {
if (value === null) return true;
if (field === "claudeMigratedAt") return typeof value === "string" && value.length <= 64;
if (field === "messages") return isRecord(value) && Object.values(value).every(item => item === null || ["boolean", "string", "number"].includes(typeof item));
return typeof value === "boolean";
}
function parse(value: unknown): NativeIntentOriginals {
if (!isRecord(value) || value.version !== 1 || !isRecord(value.fields) || Object.keys(value).length !== 2) return unsafe();
for (const [field, entry] of Object.entries(value.fields)) {
if (!(NATIVE_INTENT_FIELDS as readonly string[]).includes(field) || !isRecord(entry) || !Object.hasOwn(entry, "original")) return unsafe();
for (const [key, slot] of Object.entries(entry)) {
if (!["original", "published", "pending"].includes(key) || !validSlot(field as NativeIntentField, slot)) return unsafe();
}
}
return value as NativeIntentOriginals;
}
/** Missing reads as null. A present but unsafe or malformed record refuses rather than losing originals. */
export function readNativeIntentOriginals(): NativeIntentOriginals | null {
const path = nativeIntentOriginalsPath();
let stat;
try { stat = lstatSync(path); } catch (error) { if (isMissingPathError(error)) return null; throw error; }
if (!stat.isFile() || stat.size > RECORD_MAX_BYTES) return unsafe();
let value: unknown;
try { value = JSON.parse(readFileSync(path, "utf8")); } catch { return unsafe(); }
return parse(value);
}
function writeRecord(record: NativeIntentOriginals): void {
parse(record);
const path = nativeIntentOriginalsPath(), dir = linkDir();
assertNotRealHomeUnderTest(join(dir, ".."));
const body = `${JSON.stringify(record, null, 2)}\n`;
if (Buffer.byteLength(body) > RECORD_MAX_BYTES) unsafe();
mkdirSync(dir, { recursive: true, mode: 0o700 });
if (process.platform === "win32") hardenSecretDir(dir, { required: true });
else chmodSync(dir, 0o700);
atomicWriteFile(path, body);
if (process.platform !== "win32") chmodSync(path, 0o600);
}
function clearRecord(): void {
assertNotRealHomeUnderTest(join(linkDir(), ".."));
try { unlinkSync(nativeIntentOriginalsPath()); } catch (error) { if (!isMissingPathError(error)) throw error; }
}
/** True when the value is one this writer published or was about to publish. */
function ownedByWriter(entry: Entry, current: NativeIntentSlot): boolean {
return (Object.hasOwn(entry, "published") && sameSlot(entry.published, current))
|| (Object.hasOwn(entry, "pending") && sameSlot(entry.pending, current));
}
/**
* Write-ahead half: call under the config mutation lock before the atomic config write. Only
* fields that actually change are recorded, so a no-op toggle claims nothing. The first capture
* of a field keeps its original forever; a pending value a crash left behind and the config
* shows is promoted to published first.
*/
export function prepareNativeIntentWrite(before: NativeIntentFields, after: NativeIntentFields): boolean {
return withConfigMutationLockSync(() => {
const changed = NATIVE_INTENT_FIELDS.filter(field => !sameSlot(before[field], after[field]));
if (!changed.length) return false;
const record = readNativeIntentOriginals() ?? { version: 1 as const, fields: {} };
for (const field of changed) {
const entry: Entry = record.fields[field] ?? { original: structuredClone(before[field]) };
if (Object.hasOwn(entry, "pending") && sameSlot(entry.pending, before[field])) entry.published = entry.pending;
entry.pending = structuredClone(after[field]);
record.fields[field] = entry;
}
writeRecord(record);
return true;
});
}
/** Completion half: mark each pending value the committed config now shows as published. */
export function publishNativeIntentWrite(actual: NativeIntentFields): void {
withConfigMutationLockSync(() => {
const record = readNativeIntentOriginals();
if (!record) return;
let changed = false;
for (const field of NATIVE_INTENT_FIELDS) {
const entry = record.fields[field];
if (!entry || !Object.hasOwn(entry, "pending") || !sameSlot(entry.pending, actual[field])) continue;
entry.published = entry.pending;
delete entry.pending;
changed = true;
}
if (changed) writeRecord(record);
});
}
/**
* Restore standalone values and remove the record once the restored config is verified.
* Idempotent: a retry after an interrupted restore finds the original or the person's own
* value and only removes the record. Returns whether a record existed.
*/
export function restoreNativeIntentOriginals(guard: () => void): boolean {
return withConfigMutationLockSync(() => {
guard();
const record = readNativeIntentOriginals();
if (!record) return false;
const fields = Object.entries(record.fields) as [NativeIntentField, Entry][];
const result = mutatePersistedConfig(config => {
guard();
let changed = false;
for (const [field, entry] of fields) {
const current = readNativeIntentField(config, field);
if (!ownedByWriter(entry, current) || sameSlot(current, entry.original)) continue;
writeNativeIntentField(config, field, entry.original);
changed = true;
}
return { changed, value: config };
});
if (result.status === "unavailable") throw new Error(`Standalone native intent could not be restored (${result.reason})`);
const verified = nativeIntentFields(readConfigForAdmittedMutation());
if (fields.some(([field, entry]) => ownedByWriter(entry, verified[field]) && !sameSlot(verified[field], entry.original))) {
throw new Error("Standalone native intent restore was not verified; rerun the operation");
}
guard();
clearRecord();
return true;
});
}