UNPKG

@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
/** * 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, ); }