@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,095 lines (1,044 loc) • 49.9 kB
text/typescript
/**
* Apply, disable and restore an opencodex provider block in a client's config.
*
* Everything here exists to keep one promise: a toggle can always be undone.
* That means every mutation snapshots first, writes atomically, and journals
* what it did — and that a mutation refuses rather than guesses whenever the
* file is not in a state we can reason about. A disable that deletes work the
* user did after us would be worse than never shipping the feature.
*
* Design of record: devlog/_fin/260802_client_toggle_api/030 and 031.
*/
import { homedir } from "node:os";
import { createClineIO, ClineTransactionError } from "./cline-io";
import { serializeClineDocument, preserveClineSelection } from "./cline-document";
import { dirname } from "node:path";
import type { ExportModel, ManagedContribution } from "../clients/config-export";
import { shouldInjectApiAuthHeader } from "../codex/inject";
import { detachedConfigSnapshot } from "../config/admitted-identity";
import { copyPlainData } from "../lib/plain-data";
import type { OcxConfig } from "../types";
import { IntegrationWriteSizeError, PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
import { inspectKiloCandidates } from "./kilo-candidates";
import {
fingerprint,
canonicalContribution,
fragmentPathsOf,
semanticContribution,
type OwnershipRecord,
} from "./ownership";
import {
protectedContributionFingerprint,
refreshablePathsOf,
semanticProtectedContributionFingerprint,
} from "./ownership-policy";
import { AmbiguousSelectorError, createdContainerPaths, mergeContribution, parseSegment, removeFragments } from "./merge";
import {
INTEGRATION_CLIENTS,
assertDroidPathsUnambiguous,
isLoopbackOnly,
resolveIntegrationPaths,
type ResolvedIntegrationPaths,
restoreOwnershipCollision,
type IntegrationClientId,
} from "./registry";
import { declaredIntegrationTarget } from "./target";
import { buildIntegrationContribution, exportContextOf, qoderLegacyCatalogConflict } from "./state";
import type { IntegrationState } from "./state";
import { serializeDocument, UnserializableValueError } from "./serialize";
import { ClientPathError } from "../clients/config-export";
import { hermesRefreshRefusal } from "./hermes-refresh";
import { supportsAliasModelNames } from "../clients/config-export/model-names";
import { staleModelNameRefusal } from "./model-name-guard";
import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
import { observeIntegration, restoreStoreDirectoryRefusal, type IntegrationWriteInput, type RefusalReason } from "./mutation-plan";
import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
import {
patchYamlFragmentSource,
sourcePrunableYamlContainers,
yamlFragmentUnsupportedStyle,
} from "./omp-yaml-source";
/**
* "comments or formatting" used to be the only refusal this path could report.
* For a flow-style container that names a cause which is not in the file, and
* DSH writes that shape itself, so the misdirection was routine rather than
* exotic: users went looking for a comment that was never there (#4260).
*/
function yamlRefusalReason(
source: string,
path: readonly string[],
configPath: string,
outcome: string,
): string {
if (yamlFragmentUnsupportedStyle(source, path)) {
return `${configPath} writes ${path.join(".")} as a flow mapping or sequence, a YAML style opencodex will not re-render, so ${outcome}`;
}
return `${configPath} uses YAML source opencodex cannot patch without risking unrelated comments or formatting, so ${outcome}`;
}
import { withIntegrationWriterLock, type IntegrationWriterLockSeams } from "./writer-lock";
import { withConfigDirHardeningSettled } from "../config/paths";
import { WindowsSecretAclSettleTimeoutError } from "../lib/windows-secret-acl";
/**
* Owned by the planner so a plan can report a refusal without depending on the writer, and
* re-exported here because this module was its original home and every caller imports it from
* the writer.
*/
export type { IntegrationWriteInput, RefusalReason };
export interface WriteOk {
ok: true;
changed: boolean;
state: IntegrationState;
clientId: IntegrationClientId;
opId?: string;
message: string;
}
export interface WriteRefused {
ok: false;
reason: RefusalReason;
state: IntegrationState;
clientId: IntegrationClientId;
message: string;
/** Absolute path of a recoverable snapshot, when one exists. */
snapshotPath?: string;
/** True when compensation itself failed and the file is intermediate. */
residual?: boolean;
}
export type WriteOutcome = WriteOk | WriteRefused;
export interface IntegrationRestoreInput extends IntegrationWriteInput {
opId: string;
confirmDrift?: boolean;
}
function refuse(
clientId: IntegrationClientId,
reason: RefusalReason,
state: IntegrationState,
message: string,
snapshotPath?: string,
): WriteRefused {
return { ok: false, reason, state, clientId, message, ...(snapshotPath ? { snapshotPath } : {}) };
}
function messageOf(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}
interface CommitArgs {
io: IntegrationIO;
store: IntegrationStateStore;
clientId: IntegrationClientId;
configPath: string;
before: string | null;
nextText: string | null;
record: OwnershipRecord | null;
priorRecord: OwnershipRecord | null;
entry: JournalEntry;
state: IntegrationState;
snapshotPath?: string;
}
/**
* Client file, then ownership record, then journal row.
*
* The row is last on purpose: a record without a row is a thin history, while
* a row without a record would advertise an operation the classifier cannot
* corroborate. If either bookkeeping step fails we put the file back AND
* restore the ownership the operation replaced.
*/
function commit(args: CommitArgs): WriteOutcome {
const { io, clientId, configPath } = args;
let transactionStarted = false;
try {
if (io.beginTransaction) {
io.beginTransaction(args);
transactionStarted = true;
}
if (args.nextText === null) io.removeFile(configPath);
else {
io.mkdirp(dirname(configPath));
io.writeText(configPath, args.nextText);
}
} catch (error) {
if (transactionStarted) return compensate(args, error, "could not write both Cline files");
if (error instanceof IntegrationWriteSizeError && args.snapshotPath) {
try {
args.store.discardUncommittedSnapshot(clientId, args.entry.opId);
} catch (cleanupError) {
return refuse(clientId, "write_failed", args.state,
`${messageOf(error)}; could not remove the unused backup: ${messageOf(cleanupError)}`, args.snapshotPath);
}
return refuse(clientId, "write_failed", args.state, messageOf(error));
}
return refuse(clientId, "write_failed", args.state, messageOf(error), args.snapshotPath);
}
try {
if (args.record) io.putRecord(args.record);
else io.dropRecord(clientId);
} catch (error) {
return compensate(args, error, "could not record ownership");
}
try {
io.appendJournal(args.entry);
} catch (error) {
return compensate(args, error, "could not append the journal row");
}
io.finishTransaction?.();
return {
ok: true,
changed: true,
state: args.state,
clientId,
opId: args.entry.opId,
message: "ok",
};
}
function compensate(args: CommitArgs, cause: unknown, what: string): WriteRefused {
const { io, clientId, configPath } = args;
try {
if (args.before === null) io.removeFile(configPath);
else io.writeText(configPath, args.before);
if (args.priorRecord) io.putRecord(args.priorRecord);
else io.dropRecord(clientId);
} catch {
// Say so. A false "rolled back" is worse than the original error, because
// the user would stop looking for the file we left half-written.
return {
ok: false,
reason: "write_failed",
state: args.state,
clientId,
residual: true,
...(args.snapshotPath ? { snapshotPath: args.snapshotPath } : {}),
message: `${what}, and the change could not be rolled back. The file or its ownership record is in an intermediate state; the backup is at ${args.snapshotPath ?? "(none)"}.`,
};
}
io.finishTransaction?.();
return refuse(clientId, "write_failed", args.state, `${what}; the change was rolled back. Cause: ${messageOf(cause)}`, args.snapshotPath);
}
function snapshotAbsPath(store: IntegrationStateStore, entry: JournalEntry): string | undefined {
const snapshot = store.readSnapshot(entry);
return snapshot.kind === "stored" ? snapshot.path : undefined;
}
function sourcePreservingFragmentValue(
contribution: ManagedContribution,
path: readonly string[],
): unknown | undefined {
const fragment = contribution.fragments.find(item => (
item.path.length === path.length
&& item.path.every((key, index) => key === path[index])
));
return fragment?.value;
}
/**
* Mutation's view of the shared observation.
*
* The read, parse and classify live in the planner so a preview and the mutation it authorizes
* cannot disagree. Mutation keeps the effects a preview must not have: pending-prune maintenance
* and Cline transaction recovery both write. Translating the planner's refusal into WriteRefused
* here keeps the planner free of any dependency on this module's result type.
*/
function preflight(input: IntegrationWriteInput, operation: "apply" | "disable") {
const observed = observeIntegration(input, { maintenance: true, recover: true }, operation);
if (!observed.failed) return observed;
const { reason, state, message, snapshotPath, residual } = observed.failed;
const refused = refuse(input.clientId, reason, state, message, snapshotPath);
return { failed: residual ? { ...refused, residual: true } : refused } as const;
}
/**
* How a conflicted document is treated.
*
* `refuse` is the default and the only behavior that existed: a conflict means
* something we did not write occupies our paths, or our own block was edited,
* and guessing which one the user meant to keep is how a toggle deletes work.
*
* `overwrite` is the explicit escape hatch. It is never reached by a plain
* apply -- the caller has to ask for it by name -- because the whole value of
* the refusal is that it cannot be triggered by accident.
*/
type ConflictPolicy = "refuse" | "overwrite";
function applyOrRefreshIntegration(
input: IntegrationWriteInput,
allowAbsent: boolean,
conflictPolicy: ConflictPolicy = "refuse",
): WriteOutcome {
const pre = preflight(input, "apply");
if (pre.failed) return pre.failed;
const { store, io, clientId, spec, target, configPath, detectDir, before, parsed, contribution, record, classified } = pre;
// The detect directory preflight already resolved, so it cannot name a
// different account than the config path this operation is about to write.
if (io.statKind(detectDir) !== "dir") {
return refuse(clientId, "not_installed", "absent", `${clientId} is not installed`);
}
if (isLoopbackOnly(clientId) && shouldInjectApiAuthHeader(input.config)) {
return refuse(clientId, "non_loopback", classified.state,
`The generated ${clientId} integration is loopback-only and does not emit the admission header a non-loopback bind requires. Give it loopback access instead, through a tunnel or a local forwarder.`);
}
if (clientId === "droid" && contribution.fragments.length === 0) {
return refuse(clientId, "unsafe", classified.state, "Factory Droid has no addressable models in the selected catalog");
}
/*
* The write would land, and nothing would read it.
*
* This is deliberately a refusal rather than a warning attached to a success.
* The file is writable, our block merges cleanly, and the ownership record
* that follows would describe a real state of a real file — which is exactly
* how the original defect stayed invisible: every check the integration runs
* passed, the journal recorded a correct apply, and no model ever appeared in
* the client (#5348). Reporting the operation as done is the part that is
* wrong, so the operation does not report at all.
*
* Reached only when the store cannot be written: either this project's block
* is still in the config file, where removing it is the way forward, or the
* store is not a document whose shape has been observed. Where the store can
* be written the operation targets it and never arrives here.
*
* Apply, overwrite and refresh only. Disable removes bytes this project put
* in this file, and that removal is as effective as it ever was.
*/
if (target.ineffective !== null) {
const readsFrom = target.ineffective.store;
const fallback = `Add the proxy as a provider in ${clientId}'s own settings instead; \`ocx export --client ${clientId}\` prints the model list to copy.`;
return refuse(clientId, "superseded_store", classified.state,
target.ineffective.why === "owned-config-file"
? `${clientId} now reads its providers from ${readsFrom}, and opencodex still has a block in ${configPath}, which it no longer reads. Disable the ${clientId} integration to remove that block, then enable it again to write ${readsFrom}.`
: target.ineffective.why === "missing-store"
? `${clientId} reads its providers from ${readsFrom}, which does not exist. ${clientId} renames ${configPath} away and imports it on its next start, so opencodex will not write there. ${target.ineffective.remedy ?? fallback}`
: readsFrom === configPath
? `opencodex does not recognise the schema of ${readsFrom}, the file ${clientId} reads its providers from, so it will not merge into it. ${fallback}`
: `${clientId} now reads its providers from ${readsFrom}, whose schema opencodex does not recognise, so writing ${configPath} would change nothing it loads. ${fallback}`);
}
if (classified.state === "conflict") {
if (qoderLegacyCatalogConflict(parsed, record, contribution)) {
return refuse(clientId, "conflict", "conflict",
`${configPath} lists an opencodex model in modelConfigs.customModels that opencodex did not write; Qoder rejects the opencodex provider while that row exists, so remove or rename it first`);
}
if (conflictPolicy === "refuse") {
return refuse(clientId, "conflict", "conflict",
classified.reason === "foreign-edit"
? `${configPath} changed after opencodex wrote it`
: `${configPath} already contains an opencodex block we did not write`);
}
/*
* The caller asked for the overwrite explicitly, so the merge below runs
* against the document as it stands and our block replaces whatever holds
* our paths. Everything that makes it recoverable is shared with apply --
* the snapshot, the atomic write, the compare-before-commit recheck and the
* journal row all come from the same commit() call -- which is why this is a
* policy flag on one code path rather than a second implementation.
*/
}
/*
* `unsafe` from the classifier means the document is not one we may write
* through — today that is a container on our fragment path holding a
* non-object value the merge would replace with `{}`. Unreadable and
* unparseable files are caught earlier in preflight; this branch exists
* because the classifier can also refuse a file it CAN read.
*/
if (classified.state === "unsafe") {
return refuse(clientId, "unsafe", "unsafe",
classified.reason === "blocked-container"
? `${configPath} holds a value where opencodex would have to write a section, so applying would replace it`
: classified.reason === "ambiguous-selector"
? `${configPath} has more than one entry matching a managed selector`
: `${configPath} cannot be changed safely`);
}
/*
* An implicit catalog sync is refresh-only. Keeping this decision inside the
* writer's one preflight closes the read-then-apply race where a user could
* remove the managed block after a caller classified it as stale and a
* normal apply would silently recreate it.
*/
if (classified.state === "absent" && !allowAbsent) {
return {
ok: true,
changed: false,
state: "absent",
clientId,
message: "managed block is absent; refresh did not reconnect it",
};
}
if (classified.state === "current" && pre.modelNames === (record?.modelNames ?? "routed")) {
return { ok: true, changed: false, state: "current", clientId, message: "already applied" };
}
const hermesRefusal = hermesRefreshRefusal(pre, allowAbsent);
if (hermesRefusal) return hermesRefusal;
// A stale refresh drops what the PREVIOUS record owned before merging: a
// model that left the catalog would otherwise stay behind as an orphan the
// new record no longer covers, and disable could never remove it.
/*
* The previous record's `createdContainers` has to travel with this removal.
* Without it the refresh leaves our own empty scaffolding behind in `base`,
* `createdContainerPaths` then sees the container already present and
* concludes the user owns it, and the replacement record forgets we made it
* — so a later disable strands it forever.
*/
/*
* A document can hold a value its own format cannot round-trip through our
* renderers. That used to throw straight out of the writer and reach the
* user as a 500 with no path and no advice; it is a refusal like any other,
* and the file is untouched because this happens before any write. The
* removal and merge sit inside the same guard: a sequence holding two
* entries our selector matches is equally unwritable, and equally untouched.
*/
let created: string[];
let text: string;
try {
if (classified.state === "current") {
// A policy-only transaction retains exact bytes and container provenance.
text = before!;
created = [...(record?.createdContainers ?? [])];
} else {
// The source patcher updates this selected row in place. Keep it in the
// semantic merge too, even when we originally created it, and retain that
// provenance so disable can still remove the row when it becomes empty.
const sourceRoot = target.sourcePreservingYaml?.path[0];
const retainedRow = sourceRoot && parseSegment(sourceRoot).kind === "select" ? sourceRoot : null;
const priorCreated = record?.createdContainers ?? [];
const prunable = new Set(priorCreated.filter(path => path !== retainedRow));
const base = classified.state === "stale" && record
? removeFragments(parsed, record.fragmentPaths, prunable).doc
: classified.state === "conflict" && record
/*
* A forced overwrite of a `foreign-edit` conflict drops what the previous
* record owned for the same reason a stale refresh does: the replacement
* record covers the paths we are about to write, so a path the old record
* owned and the new one does not would be stranded forever, unremovable by
* any later disable.
*
* With NO record -- an `unowned-key` conflict -- there is nothing to drop and
* the merge runs against the user's document directly. That is correct:
* createdContainerPaths then attributes every container they already had to
* them, so a later disable removes our leaves and leaves their structure
* standing.
*/
? removeFragments(parsed, record.fragmentPaths, prunable).doc
: parsed;
// Computed against the document as it stands BEFORE the merge: afterwards
// every container exists and "did we create this?" is unanswerable.
created = createdContainerPaths(base, contribution);
if (retainedRow && priorCreated.includes(retainedRow)) created = [...new Set([retainedRow, ...created])];
const nextDocument = mergeContribution(base, contribution);
if (clientId === "cline") preserveClineSelection(parsed, nextDocument);
if (target.sourcePreservingYaml && before !== null) {
const value = sourcePreservingFragmentValue(contribution, target.sourcePreservingYaml.path);
const patched = value === undefined
? null
: patchYamlFragmentSource(
before,
target.sourcePreservingYaml.path,
{ kind: "upsert", value },
nextDocument,
);
if (patched === null) {
return refuse(clientId, "unsafe", "unsafe",
yamlRefusalReason(before, target.sourcePreservingYaml.path, configPath, "it was left alone"));
}
text = patched;
} else {
text = clientId === "cline" ? serializeClineDocument(nextDocument) : serializeDocument(nextDocument, target.format);
}
}
} catch (error) {
if (error instanceof AmbiguousSelectorError) {
return refuse(clientId, "unsafe", "unsafe",
`${configPath} holds more than one entry matching ours, so it was left alone`);
}
if (!(error instanceof UnserializableValueError)) throw error;
return refuse(clientId, "unsafe", "unsafe",
`${configPath} contains something opencodex cannot rewrite safely (${error.message}), so it was left alone`);
}
// Compare-before-commit: someone may have written between classify and now.
const recheck = io.readText(configPath);
const rechecked = recheck.kind === "text" ? recheck.text : recheck.kind === "missing" ? null : undefined;
if (rechecked === undefined || rechecked !== before) {
return refuse(clientId, "conflict", "conflict", `${configPath} changed while applying`);
}
if (clientId === "kilo") {
const candidates = inspectKiloCandidates({ io, selectedPath: configPath, env: input.env, home: input.home });
if (candidates.kind === "conflict") return refuse(clientId, "conflict", "conflict",
`${configPath} cannot be managed while ${candidates.paths.join(", ")} also defines provider.opencodex`);
if (candidates.kind === "unsafe") return refuse(clientId, "unsafe", "unsafe",
`${candidates.path} cannot be inspected safely (${candidates.why})`);
}
if (clientId === "droid") {
try {
assertDroidPathsUnambiguous(detectDir, exportContextOf(input));
} catch (error) {
if (!(error instanceof ClientPathError)) throw error;
return refuse(clientId, "unsafe", "unsafe", messageOf(error));
}
}
const opId = newOpId();
const snapshot = store.captureSnapshot(clientId, opId, before);
const at = new Date(io.now()).toISOString();
const entry: JournalEntry = {
/*
* `overwrite` is its own kind rather than reusing `apply`. The rollback list
* is the one place a user goes after a mistake, and "applied" is a lie about
* an operation that replaced a block somebody else wrote.
*/
opId, clientId,
kind: classified.state === "conflict"
? "overwrite"
: classified.state === "stale" ? "refresh" : "apply",
at, configPath,
snapshot, resultFingerprint: fingerprint(text), resultAbsent: false, priorRecord: record,
};
const refreshablePaths = refreshablePathsOf(contribution);
return commit({
io, store, clientId, configPath, before, nextText: text, state: "current",
priorRecord: record,
record: {
...(supportsAliasModelNames(clientId) ? { modelNames: pre.modelNames } : {}),
clientId, configPath, fileFingerprint: fingerprint(text),
blockFingerprint: fingerprint(canonicalContribution(contribution)),
semanticBlockFingerprint: fingerprint(semanticContribution(contribution)),
...(refreshablePaths.length > 0 ? {
protectedBlockFingerprint: protectedContributionFingerprint(contribution, refreshablePaths),
semanticProtectedBlockFingerprint: semanticProtectedContributionFingerprint(
contribution,
refreshablePaths,
),
refreshablePaths,
} : {}),
fragmentPaths: fragmentPathsOf(contribution), createdContainers: created,
appliedAt: at, opId,
},
entry,
snapshotPath: snapshotAbsPath(store, entry),
});
}
export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
return applyOrRefreshIntegration(input, true);
}
/**
* Apply over a conflicted config, replacing whatever holds our paths.
*
* Separate from `applyIntegration` and never a flag on it: a caller has to name
* this function to get the behavior, so no existing call site can acquire it by
* passing a default through.
*
* What it does NOT relax. `unsafe` still refuses -- a blocked container means the
* merge would replace a value it cannot reason about, and a snapshot is not a
* licence for that. `not_installed` and `non_loopback` still refuse; neither is a
* conflict. And a non-conflict state behaves exactly as apply does, so calling
* this on a clean file is not a way to skip any other check.
*/
export function overwriteIntegration(input: IntegrationWriteInput): WriteOutcome {
return applyOrRefreshIntegration(input, true, "overwrite");
}
/** Refresh an owned stale block, but never create or reconnect an absent one. */
export function refreshIntegration(input: IntegrationWriteInput): WriteOutcome {
return applyOrRefreshIntegration(input, false);
}
export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
const pre = preflight(input, "disable");
if (pre.failed) return pre.failed;
const { store, io, clientId, spec, target, configPath, before, parsed, record, classified, contribution } = pre;
if (classified.state === "absent") {
return { ok: true, changed: false, state: "absent", clientId, message: "not applied" };
}
if (classified.state === "conflict") {
return refuse(clientId, "conflict", "conflict",
classified.reason === "foreign-edit"
? `${configPath} changed after opencodex wrote it; disabling would discard that edit`
: qoderLegacyCatalogConflict(parsed, record, contribution)
? `${configPath} lists an opencodex model in modelConfigs.customModels that opencodex did not write; remove or rename that row, then disable again`
: `${configPath} contains an opencodex block we did not write`);
}
/*
* `unsafe` reaches here the same way it reaches apply, and the code below
* dereferences `record` on the assumption that anything past this point is
* `current` or `stale`. A blocked container has no record, so disable threw
* a TypeError and the route answered 500 — the GUI locks the switch, but the
* CLI and direct API callers do not.
*/
if (classified.state === "unsafe") {
return refuse(clientId, "unsafe", "unsafe",
classified.reason === "blocked-container"
? `${configPath} holds a value where opencodex would have to read a section, so nothing can be removed safely`
: classified.reason === "ambiguous-selector"
? `${configPath} has more than one entry matching a managed selector`
: `${configPath} cannot be changed safely`);
}
/*
* current | stale only. What makes the removal safe is the BLOCK
* fingerprint, not the file fingerprint: the classifier verified the values
* at the recorded paths are byte-for-byte what we wrote, so removing them
* cannot take a user edit with them. The file itself may have drifted — a
* json client classifies a sibling edit as stale (#1631) — which is why the
* removal runs against the document as parsed NOW, and the re-serialize is
* value-safe because non-round-tripping numbers were refused at parse time.
* Source-preserving YAML clients additionally compute which recorded
* containers are still source-empty before pruning, so a later sibling or
* comment makes its ancestor user-owned without protecting our leaf.
*/
const recordedCreated = record!.createdContainers ?? [];
const prunableCreated = target.sourcePreservingYaml && before !== null
? sourcePrunableYamlContainers(before, target.sourcePreservingYaml.path, recordedCreated)
: recordedCreated;
if (prunableCreated === null) {
return refuse(clientId, "unsafe", "unsafe",
yamlRefusalReason(before ?? "", target.sourcePreservingYaml!.path, configPath, "nothing was removed"));
}
let doc: unknown;
let removed: boolean;
try {
({ doc, removed } = removeFragments(parsed, record!.fragmentPaths, new Set(prunableCreated)));
} catch (error) {
if (!(error instanceof AmbiguousSelectorError)) throw error;
return refuse(clientId, "unsafe", "unsafe",
`${configPath} holds more than one entry matching ours, so nothing was removed`);
}
if (!removed) {
return { ok: true, changed: false, state: "absent", clientId, message: "nothing to remove" };
}
let text: string;
try {
if (target.sourcePreservingYaml && before !== null) {
const patched = patchYamlFragmentSource(before, target.sourcePreservingYaml.path, {
kind: "remove",
createdContainers: prunableCreated,
}, doc);
if (patched === null) {
return refuse(clientId, "unsafe", "unsafe",
yamlRefusalReason(before, target.sourcePreservingYaml.path, configPath, "nothing was removed"));
}
text = patched;
} else {
text = clientId === "cline" ? serializeClineDocument(doc) : serializeDocument(doc, target.format);
}
} catch (error) {
if (!(error instanceof UnserializableValueError)) throw error;
return refuse(clientId, "unsafe", "unsafe",
`${configPath} contains something opencodex cannot rewrite safely (${error.message}), so nothing was removed`);
}
const recheck = io.readText(configPath);
const rechecked = recheck.kind === "text" ? recheck.text : recheck.kind === "missing" ? null : undefined;
if (rechecked === undefined || rechecked !== before) {
return refuse(clientId, "conflict", "conflict", `${configPath} changed while disabling`);
}
const opId = newOpId();
const snapshot = store.captureSnapshot(clientId, opId, before);
const at = new Date(io.now()).toISOString();
const entry: JournalEntry = {
opId, clientId, kind: "disable", at, configPath, snapshot,
resultFingerprint: fingerprint(text), resultAbsent: false, priorRecord: record,
};
return commit({
io, store, clientId, configPath, before, nextText: text, state: "absent",
record: null, priorRecord: record, entry,
snapshotPath: snapshotAbsPath(store, entry),
});
}
export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome {
const store = input.store ?? createIntegrationStateStore();
let io = input.io ?? defaultIntegrationIO(store);
const entry = store.findOperation(input.opId);
if (!entry) throw new Error(`unknown operation ${input.opId}`);
if (entry.clientId !== input.clientId) throw new Error("restore input names a different client than the operation");
const clientId = entry.clientId;
let resolvedPath: string;
try {
resolvedPath = clientId === "zcode" || !input.resolvedPaths
? resolveIntegrationPaths(clientId, input.env, input.home, undefined, io).configPath
: input.resolvedPaths.configPath;
} catch (error) {
if (!(error instanceof ClientPathError)) throw error;
return refuse(clientId, "unsafe", "unsafe", error.message);
}
const configPath = entry.configPath;
/*
* Restore acts on the path the operation was journaled against. Resolving a
* different path here would let an operation recorded for one home delete a
* file in another — but a client may legally have written more than one file,
* so the question is whether this client still names that location, not
* whether it is the config file. The answer also carries the contribution
* shape those bytes are in, which is what the state below is measured against.
*/
const rowTarget = declaredIntegrationTarget({
clientId, configPath, resolvedConfigPath: resolvedPath, env: input.env, home: input.home, io,
});
if (rowTarget === null) {
return refuse(clientId, "conflict", "conflict",
`that operation was recorded for ${configPath}, which this client no longer writes; it now resolves to ${resolvedPath}`);
}
const directoryRefusal = restoreStoreDirectoryRefusal(input, configPath, io);
if (directoryRefusal !== null) {
return refuse(clientId, "unsafe", "unsafe", directoryRefusal);
}
/*
* Preview refuses this in observeRestore. Refusing here too is what keeps an
* undo of an older candidate from replacing the record a newer candidate owns.
*/
const currentOwner = store.readRecords()[clientId] ?? null;
const collision = restoreOwnershipCollision({
clientId,
journaledPath: configPath,
currentPath: currentOwner && currentOwner.clientId === clientId ? currentOwner.configPath : null,
env: input.env,
home: input.home,
});
if (collision !== null) {
return refuse(clientId, "conflict", "conflict", collision);
}
if (clientId === "cline") {
try { io = createClineIO(io, configPath, store, true); }
catch (error) {
if (!(error instanceof ClineTransactionError)) throw error;
return { ...refuse(clientId, "unsafe", "unsafe", error.message, error.snapshotPath), residual: true };
}
}
const snapshot = store.readSnapshot(entry);
if (snapshot.kind === "expired") {
return refuse(clientId, "snapshot_expired", "absent", "that backup has expired");
}
const backupHint = snapshot.kind === "stored" ? snapshot.path : undefined;
const target = loadTarget(io, configPath);
if (!target.ok) {
return refuse(clientId, "unsafe", "unsafe",
target.why === "read-failed"
? `${configPath} exists but could not be read; the backup is at ${backupHint ?? "(none)"}`
: `${configPath} is not a regular file; the backup is at ${backupHint ?? "(none)"}`,
backupHint);
}
const current = target.before;
/*
* Drift: the file changed after the operation we are undoing.
*
* Through the shared matcher, because `fingerprint(current ?? "")` treated a
* MISSING file as an empty one — so restoring an operation whose result was
* absence, with the file still absent, read as drift and demanded a
* confirmation for edits nobody had made. The journal meanwhile offered the
* same row as Undo.
*/
if (!matchesOperationResult(entry, current) && !input.confirmDrift) {
return refuse(clientId, "drift_requires_confirm", "conflict",
"this file changed after that operation; confirm to replace it (the current version is backed up first)");
}
// Restore is itself journaled and itself undoable: snapshot the CURRENT file
// first, so a confirmed drift-restore never destroys the newer edits.
const opId = newOpId();
const preSnapshot = store.captureSnapshot(clientId, opId, current);
const restoredText = snapshot.kind === "none" ? null : snapshot.text;
// Provenance is RESTORED, never re-derived: `priorRecord` described these
// exact bytes when the snapshot was taken. Re-deriving it from the file would
// mean guessing which entries are ours, and a wrong guess deletes a user's.
const restoredRecord = entry.priorRecord;
let restoredDocument = clientId === "droid" && restoredText !== null ? parseConfig(restoredText, "json") : undefined;
if (clientId === "commandcode" && restoredText !== null) {
const parsed = parseConfig(restoredText, "json");
// Restoring raw snapshot bytes must remain possible even when they are not parseable.
restoredDocument = parsed === PARSE_FAILED ? undefined : parsed;
}
const fresh = buildIntegrationContribution(
{ ...input, droidReasoningDefaults: undefined }, rowTarget,
restoredDocument,
restoredRecord,
);
/*
* Does the restored record actually describe the restored bytes?
*
* It usually does — `priorRecord` was written for exactly this snapshot. But
* a CONFIRMED drift-restore snapshots the user's edited file first, and
* undoing that restore puts those edited bytes back while carrying a record
* that describes what opencodex had written. Overwriting the record's
* fingerprint with the restored bytes then laundered a foreign edit into
* owned content: the state read `current`, and a later disable deleted
* fields the user had added by hand.
*/
const restoredFingerprint = restoredText === null ? "" : fingerprint(restoredText);
const recordDescribesBytes = restoredRecord !== null
&& restoredRecord.fileFingerprint === restoredFingerprint;
const state: IntegrationState = restoredRecord === null
? (restoredText === null ? "absent" : "conflict")
: !recordDescribesBytes
? "conflict"
: (
restoredRecord.semanticBlockFingerprint === fingerprint(semanticContribution(fresh))
|| restoredRecord.blockFingerprint === fingerprint(canonicalContribution(fresh))
)
? "current"
: "stale";
const at = new Date(io.now()).toISOString();
const priorRecord = store.readRecords()[clientId] ?? null;
const restoreEntry: JournalEntry = {
opId, clientId, kind: "restore", at, configPath, snapshot: preSnapshot,
resultFingerprint: restoredText === null ? "" : fingerprint(restoredText),
resultAbsent: restoredText === null,
priorRecord,
};
return commit({
io, store, clientId, configPath, before: current, nextText: restoredText, state,
priorRecord,
/*
* Keep the record's ORIGINAL `fileFingerprint`. Restoring bytes it does not
* describe leaves the classifier reading `conflict`, which is the honest
* answer — we are no longer sure the block on disk is ours, and refusing
* is what stops a disable from deleting the user's edit.
*/
record: restoredRecord === null ? null : {
...restoredRecord,
appliedAt: at,
opId,
},
entry: restoreEntry,
snapshotPath: snapshotAbsPath(store, restoreEntry),
});
}
export interface CoordinatedIntegrationOptions {
lockSeams?: IntegrationWriterLockSeams;
/**
* Checked after the input is frozen and the writer lock is held, before any side effect.
*
* A confirmation is a statement about state the operator was shown. Checking it out here, where
* the lock already excludes cooperating writers, is what makes it a decision about the same
* state the mutation is about to change rather than about state from a moment earlier. A
* non-null result refuses without writing anything.
*/
revalidate?: (frozen: IntegrationWriteInput) => Promise<WriteOutcome | null>;
/**
* Synchronous last word, evaluated with no await between it and the transaction (after
* `revalidate` and any lock acquisition). A non-null result refuses without writing.
*/
guard?: (frozen: IntegrationWriteInput) => WriteOutcome | null;
/**
* Restore's own synchronous last word, evaluated immediately before the restore transaction
* with no await in between. Restore deliberately ignores `guard` (the background-refresh
* admission hook), so a caller that must re-prove a boundary at restore time uses this one.
*/
restoreGuard?: (frozen: IntegrationWriteInput) => WriteOutcome | null;
}
/** Freeze all mutable resolution seams before the first lock await. */
type FrozenIntegrationInput = IntegrationWriteInput & {
store: IntegrationStateStore;
io: IntegrationIO;
env: NodeJS.ProcessEnv;
home: string;
resolvedPaths: ResolvedIntegrationPaths;
};
/**
* An input this write cannot hold still.
*
* A coordinated write checks a plan and then writes a document from the same input, with an await
* in between. Anything it cannot copy would have to be read from the caller's object twice, and
* the second read is not the one that was checked. Refusing is bounded and says so; carrying the
* reference and calling it a frozen input would not be.
*/
class UncopyableIntegrationInputError extends Error {}
function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegrationInput {
const env = { ...(input.env ?? process.env) };
const home = input.home ?? homedir();
const store = input.store ?? createIntegrationStateStore();
const io = input.io ?? defaultIntegrationIO(store);
const spec = INTEGRATION_CLIENTS[input.clientId];
const config = detachedConfigSnapshot(input.config);
if (config === null) {
throw new UncopyableIntegrationInputError("the proxy configuration could not be captured for this write");
}
const models = copyPlainData(input.models);
if (!models.ok) {
throw new UncopyableIntegrationInputError("the model roster could not be captured for this write");
}
const droidReasoningDefaults = input.droidReasoningDefaults === undefined
? undefined
: copyPlainData(input.droidReasoningDefaults);
if (droidReasoningDefaults !== undefined && !droidReasoningDefaults.ok) {
throw new UncopyableIntegrationInputError("Droid reasoning defaults could not be captured for this write");
}
/*
* One resolution for both paths. Aside derives them from the account id in
* its manifest, so two independent calls could verify one account's install
* and then write another account's catalog if a switch landed between them.
*/
const resolvedPaths = input.resolvedPaths
? { ...input.resolvedPaths }
: resolveIntegrationPaths(input.clientId, env, home, exportContextOf({ ...input, config, models: models.value }), io);
/*
* The configuration and the roster are seams like the others, and they were the two still held
* by reference. A coordinated write plans from this input, awaits the writer lock and a
* revalidation, and only then serializes the document from it. A management route editing the
* live configuration, or a caller editing the model objects it passed in, would have been
* checked in one state and written from another, which is the substitution the fingerprint
* exists to prevent. Copying both here gives the plan and the document one input.
*/
return {
...input, config, models: models.value,
...(droidReasoningDefaults === undefined ? {} : { droidReasoningDefaults: droidReasoningDefaults.value }),
env, home, store, io, resolvedPaths,
};
}
function tryFreezeIntegrationInput(input: IntegrationWriteInput):
| { ok: true; value: FrozenIntegrationInput }
| { ok: false; refusal: WriteRefused } {
try {
return { ok: true, value: freezeIntegrationInput(input) };
} catch (error) {
if (error instanceof UncopyableIntegrationInputError) {
return { ok: false, refusal: refuse(input.clientId, "unsafe", "unsafe", error.message) };
}
if (!(error instanceof ClientPathError)) throw error;
return {
ok: false,
refusal: refuse(input.clientId, "unsafe", "unsafe", error.message),
};
}
}
/**
* The store lock to hold beside the config file's, or null.
*
* Only for a store whose directory exists: a lock is never what creates a
* client's profile. A store path that cannot be resolved names nothing to lock;
* target resolution reports it on its own.
*/
function storeLockFile(frozen: FrozenIntegrationInput): string | null {
const declared = INTEGRATION_CLIENTS[frozen.clientId].currentStore;
if (!declared?.lockFile) return null;
let storePath: string;
try {
storePath = declared.path(frozen.env, frozen.home, frozen.io);
} catch (error) {
if (error instanceof ClientPathError) return null;
throw error;
}
return frozen.io.statKind(dirname(storePath)) === "dir" ? declared.lockFile(storePath) : null;
}
/**
* Hold the config file's sibling lock, then the store's. Every operation takes
* them in that order, so two of ours cannot deadlock, and the client's own
* writer only ever holds one of them.
*/
function withClientLocks(
frozen: FrozenIntegrationInput,
suffix: ".lock",
operation: () => WriteOutcome,
options?: CoordinatedIntegrationOptions,
): Promise<WriteOutcome> {
const run = async (heldStoreLock: string | null): Promise<WriteOutcome> => {
const refused = await options?.revalidate?.(frozen);
if (refused) return refused;
let required: string | null = null;
const outcome = await settledTransaction(frozen, () => {
// A profile can appear while revalidation or ACL admission awaits. Acquire its lock and
// repeat the validation before observing or mutating its document. The probe sits inside
// the admitted callback: no await between the last store probe and the transaction.
required = storeLockFile(frozen);
if (required !== null && required !== heldStoreLock) return null;
return operation();
});
if (outcome !== null) return outcome;
const lock = required as string | null;
if (lock === null) throw new Error("integration store lock probe returned no lock to acquire");
return withIntegrationWriterLock(lock, () => run(lock), options?.lockSeams, ".lock");
};
return withIntegrationWriterLock(frozen.resolvedPaths.configPath, () => {
// Decide only after the outer lock has actually been acquired.
const storeLock = storeLockFile(frozen);
return storeLock === null ? run(null)
: withIntegrationWriterLock(storeLock, () => run(storeLock), options?.lockSeams, ".lock");
}, options?.lockSeams, suffix);
}
/**
* Run one synchronous integration transaction after overlapping config-root ACL work (#7815).
*
* The transaction writes ownership records, the journal and snapshots under the integrations
* store with required ACLs. On Windows a config load can leave the optional config-root harden
* in flight, and its inheritance work can drop a grant this transaction just applied. The store
* root is the admission directory: settlement covers its ancestors, so the config-root flight is
* waited for. An admission that times out never entered the transaction and is refused without a
* write; a timeout thrown from inside the transaction keeps the transaction's own handling.
*/
async function settledTransaction<T>(frozen: FrozenIntegrationInput, transaction: () => T): Promise<T | WriteRefused> {
let entered = false;
try {
return await withConfigDirHardeningSettled(frozen.store.root, () => {
entered = true;
return transaction();
});
} catch (error) {
if (entered || !(error instanceof WindowsSecretAclSettleTimeoutError)) throw error;
return refuse(frozen.clientId, "write_failed", "unsafe",
"The opencodex config directory was still being secured, so nothing was written. Try again in a moment.");
}
}
async function coordinatedWrite(
input: IntegrationWriteInput,
operation: (frozen: IntegrationWriteInput) => WriteOutcome,
options?: CoordinatedIntegrationOptions,
operationKind: "apply" | "overwrite" | "disable" = "apply",
): Promise<WriteOutcome> {
const prepared = tryFreezeIntegrationInput(input);
if (!prepared.ok) return prepared.refusal;
const frozen = prepared.value;
const spec = INTEGRATION_CLIENTS[frozen.clientId];
const guarded = (bound: IntegrationWriteInput) => options?.guard?.(bound)
?? staleModelNameRefusal(bound, input.config, operationKind) ?? operation(bound);
if (!spec.writerLock) {
const refused = await options?.revalidate?.(frozen);
return refused ?? settledTransaction(frozen, () => guarded(frozen));
}
// An absent client home is not created merely to acquire a sibling lock.
if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
const refused = await options?.revalidate?.(frozen);
if (refused) return refused;
const absent = await settledTransaction(frozen, () =>
frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir" ? guarded(frozen) : null);
if (absent !== null) return absent;
}
return withClientLocks(
frozen,
spec.writerLock.suffix,
() => guarded(frozen),
options,
);
}
export function applyIntegrationCoordinated(
input: IntegrationWriteInput,
options?: CoordinatedIntegrationOptions,
): Promise<WriteOutcome> {
return coordinatedWrite(input, applyIntegration, options);
}
export function refreshIntegrationCoordinated(
input: IntegrationWriteInput,
options?: CoordinatedIntegrationOptions,
): Promise<WriteOutcome> {
return coordinatedWrite(input, refreshIntegration, options);
}
export function overwriteIntegrationCoordinated(
input: IntegrationWriteInput,
options?: CoordinatedIntegrationOptions,
): Promise<WriteOutcome> {
return coordinatedWrite(input, overwriteIntegration, options, "overwrite");
}
export function disableIntegrationCoordinated(
input: IntegrationWriteInput,
options?: CoordinatedIntegrationOptions,
): Promise<WriteOutcome> {
return coordinatedWrite(input, disableIntegration, options, "disable");
}
export async function restoreIntegrationCoordinated(
input: IntegrationRestoreInput,
options?: CoordinatedIntegrationOptions,
): Promise<WriteOutcome> {
const prepared = tryFreezeIntegrationInput(input);
if (!prepared.ok) return prepared.refusal;
const frozen = prepared.value;
const spec = INTEGRATION_CLIENTS[frozen.clientId];
// Nothing awaits between restoreGuard and the restore transaction.
const run = () => options?.restoreGuard?.(frozen)
?? restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift });
if (!spec.writerLock) {
const refused = await options?.revalidate?.(frozen);
return refused ?? settledTransaction(frozen, run);
}
if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
return refuse(
frozen.clientId,
"unsafe",
"unsafe",
`${frozen.resolvedPaths.detectDir} is missing; restore will not create the client home`,
);
}
return withClientLocks(
frozen,
spec.writerLock.suffix,
run,
options,
);
}