UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

1,065 lines (1,017 loc) • 49.7 kB
/** * Value-free planning for integration mutations. * * An operator confirming "apply", "overwrite", "disable" or "undo" is agreeing to consequences * nobody has shown them. This module computes those consequences as bounded managed schema paths * and closed change kinds, and binds them to a fingerprint over every input the decision rested * on, so a confirmation can be refused when the state it described has moved. * * Two rules give the output its safety. Nothing here is a value: paths are structural, and a * segment that is not representable in the managed grammar is dropped rather than echoed, because * an ownership record on disk accepts arbitrary strings and is not a validation authority. And * nothing here writes: this module owns no IO, takes no lock, and must never import the writer. * The dependency direction is state/ownership/merge into here, and here into the writer and the * preview route. */ import { createHash } from "node:crypto"; import { dirname } from "node:path"; import { canonicalContribution, fingerprint, type OwnershipRecord } from "./ownership"; import { ClientPathError } from "../clients/client-path"; import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export"; import { OPENCODE_PROVIDER_ID } from "../clients/config-export/constants"; import { resolveModelNames, type ExportModelNames } from "../clients/config-export/model-names"; import { ZCODE_STORE_MODEL_RULES_PATH, ZCODE_STORE_PROVIDER_RULES_PATH, } from "../clients/config-export/zcode-store"; import { createClineIO, ClineTransactionError } from "./cline-io"; import { parseClineDocument } from "./cline-document"; import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io"; import { INTEGRATION_CLIENTS, boundIntegrationConfigPath, assertDroidPathsUnambiguous, assertDroidRecordedSettingsUnambiguous, isLoopbackOnly, resolveIntegrationPaths, type ResolvedIntegrationPaths, restoreOwnershipCollision, type IntegrationClientId, } from "./registry"; import { declaredIntegrationTarget, resolveIntegrationTarget, type IneffectiveWrite, type IneffectiveWriteReason, type IntegrationTarget } from "./target"; import { shouldInjectApiAuthHeader } from "../codex/inject"; import { buildIntegrationContribution, classifyIntegration, exportContextOf, qoderLegacyCatalogConflict, readPath, type IntegrationState, type StateReason } from "./state"; import { inspectKiloCandidates } from "./kilo-candidates"; import { InvalidSelectorError, UnrepresentableSelectorError } from "./merge"; import { createIntegrationStateStore, type IntegrationStateStore } from "./store"; import type { OcxConfig } from "../types"; import { matchesOperationResult, type JournalEntry } from "./journal"; /** * Why a mutation refused. Declared here rather than in the writer so the planner can report a * refusal without depending on the module that performs writes; the writer re-exports it, so this * is a move rather than a second vocabulary. */ export type RefusalReason = | "not_installed" | "conflict" | "unsafe" | "non_loopback" | "superseded_store" | "drift_requires_confirm" | "snapshot_expired" | "write_failed"; export type IntegrationPlanOperation = "apply" | "overwrite" | "disable" | "restore"; export type IntegrationPlanChangeKind = "add" | "replace" | "remove" | "snapshot" | "ownership" | "journal"; export type IntegrationPlanForeignEdit = "none" | "unowned" | "foreign-edit" | "drift"; /** * Effects that are not places in the client's document. They carry no disk location and no value, * so an operator learns that history will be written without learning where it lives. */ export const PLAN_SNAPSHOT_PATH = "$snapshot"; export const PLAN_OWNERSHIP_PATH = "$ownership"; export const PLAN_JOURNAL_PATH = "$journal"; /** * Upper bound on reported changes. Above the largest contribution any registered client builds and * well below a response worth truncating, so the cap is a guard rather than a routine limit. */ export const PLAN_CHANGE_LIMIT = 256; export interface IntegrationPlanChange { readonly kind: IntegrationPlanChangeKind; readonly path: string; } export interface IntegrationMutationPlan { readonly version: 1; readonly clientId: IntegrationClientId; readonly operation: IntegrationPlanOperation; readonly state: IntegrationState; readonly foreignEdit: IntegrationPlanForeignEdit; readonly changes: readonly IntegrationPlanChange[]; readonly fingerprint: string; readonly canApply: boolean; /** * Whether confirming would write at all. * * An apply against an already-current file and a disable against an absent one both succeed * while writing nothing, so reporting a snapshot and a journal row for them would describe * consequences that never happen. */ readonly willChange: boolean; readonly refusalReason?: RefusalReason; /** * `superseded_store` only: why the store the client reads is not written. The store's location * stays on the status row (`supersededBy`); the plan names no file. */ readonly supersededReason?: IneffectiveWriteReason; /** `missing-store` only: the document that recreates the store, so the remedy can name it. */ readonly missingStoreDocument?: string; readonly profileId?: number; } /** A position whose observed value is never published, only its presence. */ export const DYNAMIC_SEGMENT = "*"; /** * Where each client's managed fragments live, declared rather than inferred. * * A general "looks like a plain key" rule is not good enough, and Kimi is the proof: it writes one * fragment per model at `models.<alias>`, so an alphanumeric allowlist would publish a user's * model identifier verbatim. The same rule would accept any plain path sitting in an ownership * record, and a record on disk is not a validation authority. * * So a path is published only when it matches one of these templates exactly. Static segments must * match literally, a DYNAMIC_SEGMENT position accepts any observed segment, and the string that * leaves this module is the TEMPLATE rather than the observed path. That is what makes publishing * a value structurally impossible instead of merely unlikely. * * The satisfies clause makes a new client a type error here, so nobody can add one whose managed * paths silently have no declaration. */ const CLIENT_MANAGED_PATHS = { qoder: [["providers", OPENCODE_PROVIDER_ID], ["modelConfigs", "customModels", DYNAMIC_SEGMENT]], "qoder-cn": [["providers", OPENCODE_PROVIDER_ID], ["modelConfigs", "customModels", DYNAMIC_SEGMENT]], workbuddy: [["models", DYNAMIC_SEGMENT], [DYNAMIC_SEGMENT]], "workbuddy-ai": [["models", DYNAMIC_SEGMENT], [DYNAMIC_SEGMENT]], opencode: [["provider", OPENCODE_PROVIDER_ID], ["providers", OPENCODE_PROVIDER_ID]], pi: [["providers", OPENCODE_PROVIDER_ID]], "gentle-shell": [["providers", OPENCODE_PROVIDER_ID]], omp: [["providers", OPENCODE_PROVIDER_ID]], hermes: [["providers", OPENCODE_PROVIDER_ID]], openclaw: [["models", "providers", OPENCODE_PROVIDER_ID]], kimi: [["providers", OPENCODE_PROVIDER_ID], ["models", DYNAMIC_SEGMENT]], gajae: [["providers", OPENCODE_PROVIDER_ID]], dsh: [["llm-pi-ai", "providers", OPENCODE_PROVIDER_ID], ["[id=llm-pi-ai]", "config", "providers", OPENCODE_PROVIDER_ID]], mcode: [["custom_provider", OPENCODE_PROVIDER_ID]], zcode: [ ["provider", OPENCODE_PROVIDER_ID], /* * The store the current client reads. The model rule carries the model id in * its own selector, so the published segment is the dynamic one: the template * leaves this module, never the observed path. */ [...ZCODE_STORE_PROVIDER_RULES_PATH, `[providerId=${OPENCODE_PROVIDER_ID}]`], [...ZCODE_STORE_MODEL_RULES_PATH, DYNAMIC_SEGMENT], ], /* * Both roots, because the client picks between them rather than reading both: * `document.provider ?? document.providers` in `command-code@1.66.0`. The * builder chooses the one the target already uses, and a block we wrote under * either root has to be removable from either root afterwards. */ commandcode: [["provider", OPENCODE_PROVIDER_ID], ["providers", OPENCODE_PROVIDER_ID]], prime: [["providers", OPENCODE_PROVIDER_ID]], aside: [["providers", OPENCODE_PROVIDER_ID]], raycast: [["providers", `[id=${OPENCODE_PROVIDER_ID}]`]], omo: [["providers", OPENCODE_PROVIDER_ID]], cline: [ ["settings", "providers", OPENCODE_PROVIDER_ID], ["catalog", "providers", OPENCODE_PROVIDER_ID], ], kilo: [["provider", OPENCODE_PROVIDER_ID]], droid: [["customModels", DYNAMIC_SEGMENT]], t3code: [["providerInstances", OPENCODE_PROVIDER_ID]], } satisfies Record<IntegrationClientId, readonly (readonly string[])[]>; /** Not a configuration surface. Exported so a parity case can compare it against the shipped clients. */ export const MANAGED_PATH_TEMPLATES: Readonly<Record<IntegrationClientId, readonly (readonly string[])[]>> = CLIENT_MANAGED_PATHS; function matchesTemplate(template: readonly string[], path: readonly string[]): boolean { if (template.length !== path.length) return false; return template.every((segment, index) => { const observed = path[index]; if (observed === undefined || observed.length === 0) return false; return segment === DYNAMIC_SEGMENT || segment === observed; }); } /** * The managed schema path this change touches, or null when the path is outside the client's * declared grammar. * * Null is not an error to work around. A path nobody declared is either a record written by a * different version or something arbitrary, and neither is safe to name, so the caller reports the * fixed ownership pseudo-path or a refusal instead of inventing a description. */ export function canonicalSchemaPath(clientId: IntegrationClientId, path: readonly string[]): string | null { if (path.length === 0) return null; for (const template of CLIENT_MANAGED_PATHS[clientId]) { if (matchesTemplate(template, path)) return template.join("."); } return null; } const KIND_ORDER: readonly IntegrationPlanChangeKind[] = ["add", "replace", "remove", "snapshot", "ownership", "journal"]; /** * Deterministic, deduplicated and capped. Deterministic because the fingerprint is taken over this * projection, so an unstable order would stale a plan that did not change. */ export function orderPlanChanges(changes: readonly IntegrationPlanChange[]): readonly IntegrationPlanChange[] { const seen = new Set<string>(); const unique: IntegrationPlanChange[] = []; for (const change of changes) { const key = `${change.kind}\u0000${change.path}`; if (seen.has(key)) continue; seen.add(key); unique.push(change); } unique.sort((left, right) => { const byKind = KIND_ORDER.indexOf(left.kind) - KIND_ORDER.indexOf(right.kind); if (byKind !== 0) return byKind; return left.path < right.path ? -1 : left.path > right.path ? 1 : 0; }); return Object.freeze(unique.slice(0, PLAN_CHANGE_LIMIT)); } /** * Every input the plan's authority rests on. * * `models` is here because the desired contribution is derived from it, so a model roster that * changed between preview and commit changes what would be written. `snapshot` carries a digest of * the bytes a restore would actually publish rather than only the operation id, because the id * names the row and the bytes are what lands in the user's file. */ export interface PlanFingerprintInput { readonly requestedModelNames?: ExportModelNames; readonly modelNames?: ExportModelNames; readonly operation: IntegrationPlanOperation; readonly clientId: IntegrationClientId; readonly profileId?: number; readonly configPath: string; readonly detectDir: string; /** * What the detect directory actually was when observed, not merely where it is. * * Binding only the path leaves a confirmation valid across an uninstall: the contribution is * unchanged, so every other component matches, while the answer to "is this client installed" * has flipped. The observed kind is the input the not_installed refusal is derived from. */ readonly installKind: string; /** * Whether admission policy blocks this integration, which is the non_loopback refusal's input. * * Config eligibility can change without touching the file, the record or the contribution, so a * plan that did not bind it could be confirmed after the proxy stopped being a legal target. */ readonly admissionBlocked: boolean; /** * Why a write to the target would not reach the client, or null. * * Bound for the same reason `installKind` is: it can flip without touching the * file, the record or the contribution. A client that creates its new store * while a confirmation is outstanding has changed whether the write can reach * it, and a plan that did not bind this would still authorize the write. The * reason travels with the location because both can move on their own: a store * whose schema version changes under an unchanged path is the same class of * flip as a store appearing. */ readonly ineffectiveWrite: string | null; /** * The same finding as `ineffectiveWrite`, unflattened, for the refusal's description. It is * descriptive only: the bound token above is what decides and what the fingerprint covers. */ readonly ineffective?: IneffectiveWrite | null; /** Exact current bytes, or null when the target is missing. Missing and empty are not equal. */ readonly before: string | null; readonly contribution: ManagedContribution | null; readonly record: OwnershipRecord | null; readonly models: readonly ExportModel[]; readonly restore?: { readonly opId: string; readonly entry: JournalEntry; readonly snapshotKind: string; /** Digest of the snapshot's exact text, or null when it holds none. */ readonly snapshotText: string | null; readonly confirmDrift: boolean; /** * Whether the target has changed since the operation being undone, which is the * drift_requires_confirm predicate. Passed in rather than recomputed so the plan and the * mutation read drift from the same comparison. */ readonly driftsFromResult: boolean; }; } const PLAN_FINGERPRINT_VERSION = "p3"; function digest(value: string): string { return createHash("sha256").update(value).digest("hex").slice(0, 32); } /** * An opaque optimistic-concurrency token, not authorization. * * Longer than the 16-hex ownership fingerprint because this one is supplied by a caller and * compared for equality, so accidental collision matters more than it does for a stored digest. * The version prefix means a future input set invalidates old tokens instead of silently * comparing two different meanings. */ export function planFingerprint(input: PlanFingerprintInput): string { const restore = input.restore; const components = [ PLAN_FINGERPRINT_VERSION, input.operation, input.clientId, input.requestedModelNames ?? null, input.modelNames ?? null, input.profileId === undefined ? null : input.profileId, input.configPath, input.detectDir, input.installKind, input.admissionBlocked, input.ineffectiveWrite, input.before === null ? "\u0000absent" : fingerprint(input.before), input.contribution === null ? null : fingerprint(canonicalContribution(input.contribution)), input.record === null ? null : fingerprint(JSON.stringify(input.record)), fingerprint(JSON.stringify(input.models)), restore === undefined ? null : [ restore.opId, fingerprint(JSON.stringify(restore.entry)), restore.snapshotKind, restore.snapshotText === null ? "\u0000none" : fingerprint(restore.snapshotText), restore.confirmDrift, restore.driftsFromResult, ], ]; return `${PLAN_FINGERPRINT_VERSION}:${digest(JSON.stringify(components))}`; } /** The observation facts a plan is derived from, beside the fingerprint inputs. */ export interface PlanInput extends PlanFingerprintInput { readonly classified: { readonly state: IntegrationState; readonly reason?: StateReason }; /** * The parsed target document. Whether a managed place is occupied is a fact about the file, not * about our record: an overwrite of a key somebody else wrote replaces a value even though no * record of ours mentions it. */ readonly parsed: unknown; } type PlanOutcome = | { readonly kind: "refuse"; readonly reason: RefusalReason } | { readonly kind: "noop" } | { readonly kind: "change" }; const CHANGE: PlanOutcome = { kind: "change" }; const NOOP: PlanOutcome = { kind: "noop" }; const deny = (reason: RefusalReason): PlanOutcome => ({ kind: "refuse", reason }); function foreignEditOf(input: PlanInput): IntegrationPlanForeignEdit { if (input.restore?.driftsFromResult) return "drift"; if (input.classified.reason === "unowned-key") return "unowned"; if (input.classified.reason === "foreign-edit") return "foreign-edit"; return "none"; } /** * Why this operation would refuse, in the writer's own order. * * The order is not cosmetic. An uninstalled client is reported as not installed rather than as * whatever its leftover file happens to classify as, and an unreadable or unparseable file is * reported before either, because that is the sequence the writer itself refuses in. A plan that * named a different reason than the mutation would name is worse than no plan. */ function applyOutcome(input: PlanInput): PlanOutcome { if (input.installKind !== "dir") return deny("not_installed"); if (input.admissionBlocked) return deny("non_loopback"); if (input.clientId === "droid" && input.contribution?.fragments.length === 0) return deny("unsafe"); /* * Before any file state. The document may be perfectly writable and our block * may already be current in it; neither says anything about whether the * client reads it, and reporting a change to a file nobody opens is the * defect this refusal exists for. */ if (input.ineffectiveWrite !== null) return deny("superseded_store"); // Overwrite exists precisely to proceed through a conflict the operator has been shown. // A Qoder legacy-catalog collision is not on a path overwrite replaces, so it still refuses. if (input.classified.state === "conflict" && (input.operation !== "overwrite" || qoderLegacyCatalogConflict(input.parsed, input.record, input.contribution))) return deny("conflict"); if (input.classified.state === "unsafe") return deny("unsafe"); if (input.classified.state === "current" && (input.modelNames ?? "routed") === (input.record?.modelNames ?? "routed")) return NOOP; return CHANGE; } /** * Disable answers a different question, so it asks different ones. * * It never checks installation or admission: removing what we wrote from a file that still exists * is meaningful whether or not the client is installed now, and it emits nothing that admission * policy could object to. An absent block is a success that writes nothing rather than a refusal. */ function disableOutcome(input: PlanInput): PlanOutcome { if (input.classified.state === "absent") return NOOP; if (input.classified.state === "conflict") return deny("conflict"); if (input.classified.state === "unsafe") return deny("unsafe"); return CHANGE; } function restoreOutcome(input: PlanInput): PlanOutcome { if (input.restore === undefined) return deny("unsafe"); if (input.restore.snapshotKind === "expired") return deny("snapshot_expired"); if (input.restore.driftsFromResult && !input.restore.confirmDrift) return deny("drift_requires_confirm"); return CHANGE; } /** * What this operation would do, decided the way the operation itself decides it. * * Applying one global sequence to all four was wrong: it reported disable as refused on an * uninstalled client the writer would have accepted, and it ranked the classifier's unsafe ahead * of a conflict that apply reports first. A plan is only useful if it reaches the same verdict, * for the same reason, as the mutation it describes. */ function outcomeOf(input: PlanInput): PlanOutcome { if (input.operation === "restore") return restoreOutcome(input); if (input.operation === "disable") return disableOutcome(input); return applyOutcome(input); } /** * The managed places this operation would touch, plus the history it would write. * * A path that does not canonicalize is omitted rather than guessed at. For a shipped client that * cannot happen, and the parity case proves it; what it does cover is a record written by another * version, where declining to describe a path is the honest answer and the fixed ownership entry * still tells the operator that ownership changes. */ function changesOf(input: PlanInput): readonly IntegrationPlanChange[] { const changes: IntegrationPlanChange[] = []; if (input.operation === "apply" || input.operation === "overwrite") { for (const fragment of input.contribution?.fragments ?? []) { const path = canonicalSchemaPath(input.clientId, fragment.path); if (path === null) continue; // Occupied is a fact about the document. Deciding from our own record instead would call an // overwrite of somebody else's key an addition, which is the one case overwrite exists for. const occupied = readPath(input.parsed, fragment.path) !== undefined; changes.push({ kind: occupied ? "replace" : "add", path }); } } if (input.operation === "disable") { for (const owned of input.record?.fragmentPaths ?? []) { const path = canonicalSchemaPath(input.clientId, owned); if (path === null) continue; changes.push({ kind: "remove", path }); } } if (input.operation === "restore") { /* * An undo replaces the whole document, so what it changes is the difference between the * places that are ours now and the places the row recorded as ours before that operation ran. * * Reading only the prior record got both common undos wrong. Undoing an initial apply has no * prior record, so the plan described a change to nothing at all while the undo removed the * managed block. Undoing a disable has a prior record and an empty document, so the plan said * it would replace paths the file does not currently have. * * Provenance is still restored rather than re-derived: the prior record is what says which * places are ours afterwards. The document only answers whether each of them is there now. */ const prior = new Map<string, readonly string[]>(); for (const fragment of input.restore?.entry.priorRecord?.fragmentPaths ?? []) { const path = canonicalSchemaPath(input.clientId, fragment); if (path !== null) prior.set(path, fragment); } /* * A document we could not read says nothing about whether a place is there, and restore does * not need it read: eligibility is a question about bytes. Where it cannot be read, each place * is reported as a replacement, which is what this list said before any of it was derived. */ const documentKnown = input.parsed !== PARSE_FAILED; for (const [path, fragment] of prior) { let absent = false; if (documentKnown) { try { absent = readPath(input.parsed, fragment) === undefined; } catch (error) { /* * Restore eligibility is byte-based and does not parse ownership paths. * A malformed versioned selector therefore makes this ONE descriptive * comparison unknown; it must not make preview execute a different * selector, and it must not hide the backup behind an internal error. */ if (!(error instanceof InvalidSelectorError)) throw error; } } changes.push({ kind: absent ? "add" : "replace", path }); } for (const fragment of input.record?.fragmentPaths ?? []) { const path = canonicalSchemaPath(input.clientId, fragment); if (path === null || prior.has(path)) continue; changes.push({ kind: "remove", path }); } } changes.push({ kind: "snapshot", path: PLAN_SNAPSHOT_PATH }); changes.push({ kind: "ownership", path: PLAN_OWNERSHIP_PATH }); changes.push({ kind: "journal", path: PLAN_JOURNAL_PATH }); return orderPlanChanges(changes); } /** * The whole plan, value-free. * * A refused plan is still worth returning: knowing that undo is blocked because the backup expired * is the answer an operator needs, and it carries no more detail than an allowed one. */ export function buildMutationPlan(input: PlanInput): IntegrationMutationPlan { const outcome = outcomeOf(input); return Object.freeze({ version: 1 as const, clientId: input.clientId, operation: input.operation, state: input.classified.state, foreignEdit: foreignEditOf(input), // Only a plan that would actually write describes places to write. changes: outcome.kind === "change" ? changesOf(input) : Object.freeze([]), fingerprint: planFingerprint(input), canApply: outcome.kind !== "refuse", willChange: outcome.kind === "change", ...(outcome.kind === "refuse" ? { refusalReason: outcome.reason } : {}), ...(outcome.kind === "refuse" && outcome.reason === "superseded_store" && input.ineffective ? { supersededReason: input.ineffective.why, ...(input.ineffective.emptyDocument === undefined ? {} : { missingStoreDocument: input.ineffective.emptyDocument }), } : {}), ...(input.profileId === undefined ? {} : { profileId: input.profileId }), }); } /** * The token a plan carries when observation itself refused. * * Such a plan never read the state it would have bound, so there is nothing to bind. It is safe * for every one of them to share this value because `canApply` is false, and a mutation may only * be bound to a plan that could apply. */ export const PLAN_UNBOUND_FINGERPRINT = `${PLAN_FINGERPRINT_VERSION}:unbound`; function unboundPlan( clientId: IntegrationClientId, operation: IntegrationPlanOperation, failure: IntegrationObservationFailure, profileId?: number, ): IntegrationMutationPlan { return Object.freeze({ version: 1 as const, clientId, operation, state: failure.state, foreignEdit: "none" as const, changes: Object.freeze([]), fingerprint: PLAN_UNBOUND_FINGERPRINT, canApply: false, willChange: false, refusalReason: failure.reason, ...(profileId === undefined ? {} : { profileId }), }); } /** A restore must not recreate a declared store without its client's lock. */ export function restoreStoreDirectoryRefusal( input: IntegrationWriteInput, configPath: string, io: IntegrationIO, ): string | null { const declared = INTEGRATION_CLIENTS[input.clientId].currentStore; if (!declared?.lockFile) return null; let storePath: string; try { storePath = declared.path(input.env, input.home, io); } catch (error) { if (error instanceof ClientPathError) return null; throw error; } return configPath === storePath && io.statKind(dirname(storePath)) !== "dir" ? "the client store directory is missing; restore will not create it" : null; } /** * Restore reads a different specification, so it gets its own observation. * * The writer's undo path never parses and never classifies: it compares the resolved config path * against the one the journal row was recorded for, reads the snapshot, and reads the target's * BYTES. Routing a preview through the general observation therefore refused an undo of a file * that was readable but unparseable, which is the state that most needs restoring, and accepted a * row recorded against a previous home, which is the single case path equality exists to refuse. */ export function observeRestore( input: IntegrationWriteInput, opId: string, effects: ObservationEffects, /** * The row a caller already selected, with the store it came from. * * Aside can hold more than one valid copy of the same operation, so re-resolving here could * legitimately pick a different row than the mutation will. The plan would then describe an * operation the confirmation was never about. A caller that has resolved one passes it in, and * neither side resolves again. */ selectedOperation?: { entry: JournalEntry; store: IntegrationStateStore }, ) { const store = selectedOperation?.store ?? input.store ?? createIntegrationStateStore(); let io = input.io ?? defaultIntegrationIO(store); const clientId = input.clientId; let resolved: ResolvedIntegrationPaths; try { const context = exportContextOf(input); resolved = clientId === "zcode" || !input.resolvedPaths ? resolveIntegrationPaths(clientId, input.env, input.home, context, io) : input.resolvedPaths; if (clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(resolved.detectDir, context); } catch (error) { if (!(error instanceof ClientPathError)) throw error; return { failed: observationFailure("unsafe", "unsafe", error.message) } as const; } // Coordinated restore refuses this before it looks at the row at all: an undo will not create // the client's home, so a writer-lock client without one has nothing to restore into. if (INTEGRATION_CLIENTS[clientId].writerLock && io.statKind(resolved.detectDir) !== "dir") { return { failed: observationFailure("unsafe", "unsafe", "the client home is missing; restore will not create it"), } as const; } const entry = selectedOperation?.entry ?? store.findOperation(opId); if (!entry || entry.clientId !== clientId) { return { failed: observationFailure("unsafe", "unsafe", "that operation cannot be undone") } as const; } const configPath = entry.configPath; /* * An undo acts on the path the operation was journaled against. A row recorded for one home must * never be allowed to rewrite a file in another — but a client may legally have written more than * one file, so the test is whether this client still names that location, not whether it is the * config file. The answer also carries the document shape those bytes are in. */ const rowTarget = declaredIntegrationTarget({ clientId, configPath, resolvedConfigPath: resolved.configPath, env: input.env, home: input.home, io, }); if (rowTarget === null) { return { failed: observationFailure("conflict", "conflict", "that operation was recorded for a different location"), } as const; } const directoryRefusal = restoreStoreDirectoryRefusal(input, configPath, io); if (directoryRefusal !== null) { return { failed: observationFailure("unsafe", "unsafe", directoryRefusal) } as const; } /* * A legal historical path is not enough. Another candidate can already own * the single record, and committing this row's prior record would orphan the * block that candidate still holds. Direct restore asks the same question. */ 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 { failed: observationFailure("conflict", "conflict", collision) } as const; } if (clientId === "cline") { try { io = createClineIO(io, configPath, store, effects.recover); } catch (error) { if (!(error instanceof ClineTransactionError)) throw error; return { failed: { ...observationFailure("unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const; } } const snapshot = store.readSnapshot(entry); /* * Expiry is decided before the target is read, exactly as the writer decides it. Reading first * let an expired backup over an unreadable file report the file as the problem, when the answer * the operator needs is that the backup is gone. */ if (snapshot.kind === "expired") { return { failed: observationFailure("snapshot_expired", "absent", "that backup has expired") } as const; } const target = loadTarget(io, configPath); if (!target.ok) { return { failed: observationFailure("unsafe", "unsafe", "the target cannot be read safely") } as const; } const before = target.before; return { failed: undefined, clientId, configPath, format: rowTarget.format, detectDir: resolved.detectDir, installKind: io.statKind(resolved.detectDir), entry, snapshotKind: snapshot.kind, snapshotText: snapshot.kind === "stored" ? snapshot.text : null, before, // Bytes only. Parsing here is exactly what must not happen. driftsFromResult: !matchesOperationResult(entry, before), } as const; } export interface PreviewRequest { readonly operation: IntegrationPlanOperation; /** Required for restore; names the journalled operation being undone. */ readonly opId?: string; readonly confirmDrift?: boolean; readonly profileId?: number; /** A row and store the caller already selected, so neither side resolves it twice. */ readonly resolved?: { entry: JournalEntry; store: IntegrationStateStore }; } /** * Plan an operation without performing it. * * Observation runs with both write-capable effects off, so this path prunes nothing, recovers * nothing, takes no lock and enters no mutation flight. Everything it reads is a read: the target * file, the ownership records, and for restore the journal row and its snapshot. */ export function previewIntegration(input: IntegrationWriteInput, request: PreviewRequest): IntegrationMutationPlan { // Restore never reaches the general observation, because the writer's undo path never parses // or classifies and a preview that did would answer a different question. if (request.operation === "restore") return previewRestore(input, request); const observed = observeIntegration(input, { maintenance: false, recover: false }, request.operation); if (observed.failed) return unboundPlan(input.clientId, request.operation, observed.failed, request.profileId); const shared = { operation: request.operation, clientId: observed.clientId, configPath: observed.configPath, detectDir: observed.detectDir, installKind: observed.io.statKind(observed.detectDir), // Loopback-only clients cannot carry the admission header a non-loopback bind requires. admissionBlocked: isLoopbackOnly(observed.clientId) && shouldInjectApiAuthHeader(input.config), ineffectiveWrite: observed.ineffectiveWrite, ineffective: observed.target.ineffective, before: observed.before, contribution: observed.contribution, record: observed.record, requestedModelNames: input.modelNames, modelNames: observed.modelNames, models: input.models, classified: observed.classified, parsed: observed.parsed, ...(request.profileId === undefined ? {} : { profileId: request.profileId }), }; return buildMutationPlan(shared); } /** * Which places are ours in the file this undo would rewrite, read the same way the general * observation reads them. * * Read from the store bound to the target being rewritten, never from the store a historical row * was selected out of. Aside keeps a copy of an operation in the root store while the profile's * own store holds the ownership for its file, so asking the selected row's store would have * described the wrong file's ownership. The selected store stays what it is for: the row and its * snapshot. A record written for another location grants nothing here either, which is the same * rule the writer applies. */ function currentRecordFor( input: IntegrationWriteInput, clientId: IntegrationClientId, configPath: string, ): OwnershipRecord | null { const store = input.store ?? createIntegrationStateStore(); const stored = store.readRecords()[clientId] ?? null; return stored && stored.clientId === clientId && stored.configPath === configPath ? stored : null; } /** * Plan an undo the way the writer performs one. * * State is derived from bytes alone: a missing target is absent, a target that no longer matches * the row's recorded result is a conflict, and anything else is current. Admission is not asked * about, because restore emits nothing an admission policy could object to and the writer does not * ask either. */ function previewRestore(input: IntegrationWriteInput, request: PreviewRequest): IntegrationMutationPlan { const refusal = (message: string): IntegrationMutationPlan => unboundPlan(input.clientId, "restore", { reason: "unsafe", state: "unsafe", message }, request.profileId); if (request.opId === undefined) return refusal("that operation cannot be undone"); const observed = observeRestore( input, request.opId, { maintenance: false, recover: false }, request.resolved, ); if (observed.failed) return unboundPlan(input.clientId, "restore", observed.failed, request.profileId); /* * Drift decides first. A row that recorded a file and now finds none has drifted, and calling * that absent would report a missing file as an ordinary undo while the writer refuses it * pending confirmation. Absent is only honest when the recorded result was absence too. */ const state: IntegrationState = observed.driftsFromResult ? "conflict" : observed.before === null ? "absent" : "current"; return buildMutationPlan({ operation: "restore", clientId: observed.clientId, configPath: observed.configPath, detectDir: observed.detectDir, installKind: observed.installKind, admissionBlocked: false, /* * Undo puts back bytes this project already wrote to this file. Whether the * client still reads the file does not change whether those bytes may be * restored, and refusing here would strand a user on a state they asked to * leave. */ ineffectiveWrite: null, before: observed.before, contribution: null, // Descriptive, never decisive. The record says which places are ours now and the document // says which of them the file holds, so the change list can distinguish a place this undo // adds back from one it replaces and one it takes away. Neither is allowed to refuse: an // unreadable document is reported as PARSE_FAILED and leaves every place a replacement, and // restore eligibility stays the byte comparison it was. record: currentRecordFor(input, observed.clientId, observed.configPath), models: input.models, classified: { state }, parsed: observed.before === null ? {} : observed.clientId === "cline" ? parseClineDocument(observed.before) : parseConfig(observed.before, observed.format, EXPORT_CLIENTS[observed.clientId].jsonc ? { jsonc: true } : undefined), restore: { opId: observed.entry.opId, entry: observed.entry, snapshotKind: observed.snapshotKind, snapshotText: observed.snapshotText, confirmDrift: request.confirmDrift === true, driftsFromResult: observed.driftsFromResult, }, ...(request.profileId === undefined ? {} : { profileId: request.profileId }), }); } /** * What a mutation is asked to do. Declared here because the observation below consumes it and the * planner must not depend on the writer; the writer re-exports it, so callers are unaffected. */ export interface IntegrationWriteInput { modelNames?: ExportModelNames; clientId: IntegrationClientId; models: readonly ExportModel[]; config: OcxConfig; port: number; /** Explicit Droid-only defaults; omitted means retain matching owned rows. */ droidReasoningDefaults?: Record<string, string>; env?: NodeJS.ProcessEnv; home?: string; store?: IntegrationStateStore; io?: IntegrationIO; /** Frozen once by the async coordinator; synchronous callers may omit it. */ resolvedPaths?: ResolvedIntegrationPaths; } /** A refusal in the planner's own vocabulary, so observation does not depend on the writer's result type. */ export interface IntegrationObservationFailure { readonly reason: RefusalReason; readonly state: IntegrationState; readonly message: string; readonly snapshotPath?: string; /** A Cline transaction left residue that only a mutation may clear. */ readonly residual?: boolean; } function observationFailure( reason: RefusalReason, state: IntegrationState, message: string, snapshotPath?: string, ): IntegrationObservationFailure { return { reason, state, message, ...(snapshotPath ? { snapshotPath } : {}) }; } /** * What preview and mutation are allowed to touch while looking. * * Both are false for a preview and both are true for a mutation, and neither defaults, because the * difference is the whole safety argument. `maintenance` runs pending snapshot pruning, which * writes; `recover` lets the Cline adapter repair a pending transaction, which also writes. A * preview that quietly inherited either would be a mutation wearing a read's name. */ export interface ObservationEffects { readonly maintenance: boolean; readonly recover: boolean; } /** * Detect, gate, read, parse and classify, once, for both preview and mutation. * * Extracted from the writer so a plan and the mutation it authorizes rest on the same * classification rather than two independent reads that can disagree. The ordering of refusals is * load-bearing and is preserved exactly as the writer had it. */ export function observeIntegration( input: IntegrationWriteInput, effects: ObservationEffects, operation: Exclude<IntegrationPlanOperation, "restore">, ) { const store = input.store ?? createIntegrationStateStore(); let io = input.io ?? defaultIntegrationIO(store); const clientId = input.clientId; const spec = INTEGRATION_CLIENTS[clientId]; const exportSpec = EXPORT_CLIENTS[clientId]; /* * Resolution itself can refuse: a relative OPENCLAW_* selector is rejected * because we cannot know the gateway's working directory. That is a refusal * about the user's configuration, not an internal fault, so it must not * escape as an exception — the collection route would answer 500 for the * whole Integrations page because one client is misconfigured. */ let configPath: string; let detectDir: string; let effective: IntegrationTarget; let stored: OwnershipRecord | null; try { /* * Resolve the PAIR, never one half. * * The coordinated path hands us a frozen pair, but applyIntegration, * refreshIntegration and disableIntegration are public and may be called * without one. Resolving configPath here and detectDir separately later let * an Aside account switch land between the two, so a direct apply could * verify account 1 was installed and then write account 0's catalog. */ const context = exportContextOf(input); const resolved = clientId === "zcode" || !input.resolvedPaths ? resolveIntegrationPaths(clientId, input.env, input.home, context, io) : input.resolvedPaths; if (clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(resolved.detectDir, context); detectDir = resolved.detectDir; if (clientId === "cline") io = createClineIO(io, resolved.configPath, store, effects.recover); /* * A record proves ownership of the file it was written FOR, and it is also * one of the inputs the target is chosen from: a block we already wrote to * the config file keeps this operation on that file, so disable removes what * we wrote from where we wrote it. Matching by path happens after the * target is known, because that is the path it has to match. */ stored = store.readRecords()[clientId] ?? null; const recordedPath = boundIntegrationConfigPath({ clientId, record: stored, resolvedPath: resolved.configPath, statKind: io.statKind, env: input.env, home: input.home, }); /* * Inside the same guard as resolution, because this resolver can refuse the * same way: the store is named by a client env var, and a relative one is a * misconfiguration to report rather than an exception to leak through the * collection route. */ effective = resolveIntegrationTarget({ clientId, configPath: recordedPath, io, record: stored, env: input.env, home: input.home, resolvedPaths: resolved, }); configPath = effective.configPath; if (effective.pathError && operation !== "disable") { return { failed: observationFailure("unsafe", "unsafe", effective.pathError) } as const; } } catch (error) { if (error instanceof ClineTransactionError) { return { failed: { ...observationFailure("unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const; } if (!(error instanceof ClientPathError)) throw error; return { failed: observationFailure("unsafe", "unsafe", error.message) } as const; } // Pruning writes, so only a mutation may perform it. Preview reports the state it finds. if (clientId === "kilo" && operation !== "disable") { const candidates = inspectKiloCandidates({ io, selectedPath: configPath, env: input.env, home: input.home }); if (candidates.kind !== "ok") return { failed: candidates.kind === "conflict" ? observationFailure("conflict", "conflict", `${configPath} cannot be managed while ${candidates.paths.join(", ")} also defines provider.opencodex`) : observationFailure("unsafe", "unsafe", `${candidates.path} cannot be inspected safely (${candidates.why})`), } as const; } if (effects.maintenance) store.retryPendingPrunes(); const loaded = loadTarget(io, configPath); if (!loaded.ok) { return { failed: observationFailure("unsafe", "unsafe", loaded.why === "read-failed" ? `${configPath} exists but could not be read` : `${configPath} is not a regular file`), } as const; } const before = loaded.before; const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, effective.format, exportSpec.jsonc ? { jsonc: true } : undefined); if (parsed === PARSE_FAILED) { return { failed: observationFailure("unsafe", "unsafe", `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const; } /* * The shape the TARGET's reader understands, which is not always the * client's config format: a client that moved its providers to another file * reads a different document there, and a write in the config file's shape * would be as unread as a write to the config file itself. */ // A record proves ownership of the file it was written FOR. Matching only by // client id let a record for one home authorize a write to another whose // bytes happened to hash the same — which deleted a config we never touched. const record = stored && stored.clientId === clientId && stored.configPath === configPath ? stored : null; if (operation !== "disable") { const refusal = exportSpec.validateApply?.({ ...exportContextOf(input), document: parsed }); if (refusal) return { failed: observationFailure("unsafe", "unsafe", refusal) } as const; } let contribution: ManagedContribution; let modelNames: ExportModelNames; try { modelNames = resolveModelNames(clientId, input.modelNames, record?.modelNames); contribution = buildIntegrationContribution(input, effective, parsed, record); } catch (error) { if (!(error instanceof UnrepresentableSelectorError)) throw error; return { failed: observationFailure("unsafe", "unsafe", error.message) } as const; } if (clientId === "droid" && input.models.length > 0 && contribution.fragments.length === 0 && !record) { return { failed: observationFailure("unsafe", "unsafe", "Factory Droid has no addressable models in the selected catalog") } as const; } // `configPath`/`clientId` are load-bearing, not decoration: a record proves // ownership of ONE file, and the writer mutates whatever path resolves NOW. // Without them a record written for another home directory would grant // ownership here and disable would delete fragments it never wrote. const classified = classifyIntegration({ fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId, format: effective.format, sourcePreservingYaml: effective.sourcePreservingYaml !== null, }); if (clientId === "droid" && record && (classified.state === "current" || classified.state === "stale")) { try { assertDroidRecordedSettingsUnambiguous(detectDir, parsed, record); } catch (error) { if (!(error instanceof ClientPathError)) throw error; return { failed: observationFailure("unsafe", "unsafe", error.message) } as const; } } return { failed: undefined, store, io, clientId, spec, exportSpec, target: effective, configPath, detectDir, /* * One token for the plan, because the location alone is not the input: a * store whose schema stops being one we recognise changes the answer while * its path stays exactly the same. */ ineffectiveWrite: effective.ineffective === null ? null : `${effective.ineffective.why}\u0000${effective.ineffective.store}`, before, parsed, contribution, record, classified, modelNames, } as const; }