UNPKG

@bitkyc08/opencodex

Version:

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

605 lines (590 loc) • 27.7 kB
/** * Where each file-toggle client keeps its config, and what we are allowed to do * to it. * * The export registry (src/clients/config-export.ts) says how to RENDER a * client's config. This one says where it lives, how to tell whether the client * is installed at all, and whether a remote bind is safe for it. * * Design of record: devlog/_fin/260802_client_toggle_api/021 §1. */ import { agentConfigPath, agentHomeDir } from "../clients/config-export/agent-clients"; import { homedir } from "node:os"; import { gentleShellPaths } from "../clients/gentle-shell-path"; import { assertDroidSettingsUnambiguous } from "./droid-settings"; import { readPath } from "./merge"; import type { OwnershipRecord } from "./ownership"; import type { IntegrationIO } from "./config-io"; import { dirname, join } from "node:path"; import { ClientPathError } from "../clients/client-path"; import { buildDroidContribution, qoderConfigPath, qoderHomeDir, t3codeConfigPath, t3codeHomeDir, clineConfigPath, clineSettingsDir, droidConfigPath, droidHomeDir, EXPORT_CLIENTS, asideAccountDir, asideConfigPath, asideHomeDir, dshConfigPath, dshHomeDir, gajaeConfigPath, gajaeHomeDir, hermesConfigPath, hermesHomeDir, kimiConfigPath, kimiHomeDir, mcodeConfigPath, mcodeHomeDir, omoAgentDir, omoConfigPath, ompAgentDir, ompModelsConfigPath, opencodeGlobalConfigPath, openclawConfigPath, openclawHomeDir, piAgentDir, piConfigPath, primeAgentDir, primeConfigPath, raycastAiDir, raycastConfigPath, zcodeConfigPath, zcodeHomeDir, zcodeLegacyHomeDir, ZcodeSettingsPathError, zcodeProviderStorePath, buildZcodeStoreContribution, zcodeStoreSchemaEstablished, dshProfilePatchPath, dshProfilePatchEstablished, buildDshProfilePatchContribution, DSH_PROFILE_PROVIDER_PATH, type BuildContribution, type ConfigFormat, commandCodeConfigPath, commandCodeHomeDir, kiloConfigPath, kiloHomeDir, kiloCandidatePath, KILO_CONFIG_CANDIDATES, type ExportClientId, type DroidModelEntry, type ExportContext, } from "../clients/config-export"; /** * Readability alias. WP1 owns the type; this never introduces a second one, so * the dependency only ever points backwards. */ export type IntegrationClientId = ExportClientId; export interface ResolvedIntegrationPaths { configPath: string; detectDir: string; /** Snapshot of a mutable store resolution from the same bootstrap read. */ storePath?: string; /** The default config path is only a recovery hint when the active root is unknown. */ pathError?: string; } export interface IntegrationClientSpec { id: IntegrationClientId; /** The client's config file, honoring that client's own environment override. */ configPath: (env?: NodeJS.ProcessEnv, home?: string, io?: Pick<IntegrationIO, "readText">) => string; /** Directory whose existence is the cheap "is it installed?" signal. */ detectDir: (env?: NodeJS.ProcessEnv, home?: string, io?: Pick<IntegrationIO, "readText">) => string; /** * The provider store this client reads INSTEAD of `configPath`. * * A client that moves its store between releases usually keeps a one-shot * import from the old location, and that import is exactly what makes the old * write look like it still works: it runs once, on an install that has never * created the new file, and never again. Everything after it lands in a file * the client does not open. * * A declaration carries everything needed to write the store, not only its * location: the text format, the contribution shape its reader understands, * and the predicate that says whether a document on disk is a version whose * shape has been observed. The last one is what keeps this honest — a store * we cannot establish is reported as the reason the write cannot reach the * client, never merged into on a guess. */ currentStore?: { path: (env?: NodeJS.ProcessEnv, home?: string, io?: Pick<IntegrationIO, "readText">) => string; format: ConfigFormat; establishes: (parsed: unknown) => boolean; buildContribution: BuildContribution; /** Patch only this leaf of the store, as `sourcePreservingYaml` does for the config file. */ sourcePreservingYaml?: { path: readonly string[] }; /** * The file whose `<file>.lock` sibling the client's own writer holds while * it rewrites the store. Taken after the config file's lock, whenever the * store's directory exists. */ lockFile?: (storePath: string) => string; /** * A missing store the client already manages. Writing the config file instead would not stay * where opencodex records it, so the target is reported as an ineffective write with this * remedy rather than silently writing the config file. */ missingStore?: { readsStore: (storePath: string, statKind: (path: string) => string) => boolean; /** * The document the client writes into a new store. Creating the store with exactly this is * the remedy, and it is published on its own so a surface that localizes the remedy text * can still name what to write. */ emptyDocument: string; remedy: string; }; }; /** Patch only this block-map YAML leaf; never re-render the shared file. */ sourcePreservingYaml?: { path: readonly string[] }; /** Coordinate the complete mutation through a sibling config lock. */ writerLock?: { suffix: ".lock" }; /** * Derive the config path AND the detect directory from one resolution, for a * client whose paths depend on mutable state rather than only env and home. * * Aside needs this because both paths come from the account id in * `accounts.json`: one read prevents an account switch between resolutions. * Droid uses the same seam to check competing settings against the export * context before status, preview, or mutation proceeds. */ resolvePaths?: (env?: NodeJS.ProcessEnv, home?: string, exportContext?: ExportContext, io?: Pick<IntegrationIO, "readText">) => ResolvedIntegrationPaths; /** * Where the client's config WOULD live, for a client whose real path cannot * be resolved yet. * * Only a client with `resolvePaths` needs this, and only because that * resolution can legitimately fail on a machine where the client has never * run. Aside's account id comes from a manifest the app writes at first * launch, so a never-signed-in install has no account directory and no id -- * which is "not installed", not "we cannot verify this file". * * The value is a location to SHOW, never a location to write: it names the * account root without an account, so it cannot be mistaken for a real * catalog. `resolveIntegrationPaths` still throws for callers that mutate. */ unresolvedPathHint?: (env?: NodeJS.ProcessEnv, home?: string) => string; /** * Recognize a resolution drift that is still THIS client's own file, for a * client whose config path depends on mutable world state rather than only * env and home. * * Kilo resolves to the first EXISTING candidate, so a candidate created * after apply moves resolution while the owned file still holds our block. * While this predicate accepts the recorded path, reads and mutations stay * bound to it instead of silently re-homing onto the newcomer. A client * without this hook never binds: a record from another home stays a refusal * ("a record for one home cannot authorize a write to another"). */ bindsDriftedRecord?: (recordPath: string, env?: NodeJS.ProcessEnv, home?: string) => boolean; } /** * The one place that turns a client id into the pair of paths an operation uses. * * A caller that resolves `configPath` and `detectDir` separately is correct for * every client whose paths are a pure function of env and home, and wrong for * one that reads mutable state. Routing both through here lets such a client fix * that for itself without every call site learning why. */ export function resolveIntegrationPaths( clientId: IntegrationClientId, env: NodeJS.ProcessEnv = process.env, home: string = homedir(), exportContext?: ExportContext, io?: Pick<IntegrationIO, "readText">, ): ResolvedIntegrationPaths { const spec = INTEGRATION_CLIENTS[clientId]; if (spec.resolvePaths) return spec.resolvePaths(env, home, exportContext, io); return { configPath: spec.configPath(env, home, io), detectDir: spec.detectDir(env, home, io) }; } export function assertDroidPathsUnambiguous(root: string, exportContext?: ExportContext): void { try { const generated = exportContext ? buildDroidContribution(exportContext).fragments : []; assertDroidSettingsUnambiguous(root, exportContext?.baseUrl, generated.map(fragment => (fragment.value as DroidModelEntry).model)); } catch (error) { throw new ClientPathError((error as Error).message); } } /** Check the identities still owned on disk even after they leave the catalog. */ export function assertDroidRecordedSettingsUnambiguous(root: string, parsed: unknown, record: OwnershipRecord): void { try { const byEndpoint = new Map<string, Set<string>>(); for (const path of record.fragmentPaths) { const row = readPath(parsed, path) as Partial<DroidModelEntry> | undefined; if (typeof row?.baseUrl !== "string" || typeof row.model !== "string") { throw new Error("Cannot verify recorded Factory Droid rows"); } const models = byEndpoint.get(row.baseUrl) ?? new Set<string>(); models.add(row.model); byEndpoint.set(row.baseUrl, models); } for (const [baseUrl, models] of byEndpoint) assertDroidSettingsUnambiguous(root, baseUrl, [...models]); } catch (error) { throw new ClientPathError((error as Error).message); } } /** * The location to name when resolution refused, or `""` when there is none. * * A read-only surface reporting "unresolvable" with an empty path told the user * nothing they could act on, and for Aside it also reported the wrong thing: an * absent account manifest is the ordinary state of an installed-but-never-run * Aside, and the honest answer there is that it is not signed in. * * `""` is a sentinel, not a path: it is what `readIntegrationState` reads to * decide between not-installed and cannot-verify. A config path is never * legitimately empty, and a hint is always an absolute `join` result, so the two * cannot be confused. */ export function unresolvedPathHintFor( clientId: IntegrationClientId, env: NodeJS.ProcessEnv = process.env, home: string = homedir(), ): string { const spec = INTEGRATION_CLIENTS[clientId]; if (!spec.unresolvedPathHint) return ""; try { return spec.unresolvedPathHint(env, home); } catch (error) { /* * Only a path refusal is absorbed. An unqualified catch here would also * swallow a TypeError from a future implementor's typo, an * ERR_INVALID_ARG_TYPE out of `join`, or an EACCES from a resolver that * touches the filesystem -- turning a programming error into a silently * degraded badge. `readIntegrationState` narrows the same way at its own * catch, and this is the matching half. */ if (!(error instanceof ClientPathError)) throw error; return ""; } } /** * True when the client has nowhere to put the dedicated admission header a * non-loopback bind requires, so a generated config would simply be rejected. * * Read from the export registry rather than restated here: two lists of the * same fact drift, and this one decides whether we write a file that 401s. */ export function isLoopbackOnly(clientId: IntegrationClientId): boolean { return EXPORT_CLIENTS[clientId].loopbackOnly; } function xdgConfigHome(env: NodeJS.ProcessEnv, home: string): string { const xdg = env.XDG_CONFIG_HOME; return xdg && xdg.length > 0 ? xdg : join(home, ".config"); } export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientSpec> = { qoder: { id: "qoder", configPath: qoderConfigPath, detectDir: (env = process.env, home = homedir()) => qoderHomeDir(env, home), }, ...Object.fromEntries((["qoder-cn", "workbuddy", "workbuddy-ai"] as const).map(id => [id, { id, configPath: (env = process.env, home = homedir()) => agentConfigPath(id, env, home), detectDir: (env = process.env, home = homedir()) => agentHomeDir(id, env, home), }])) as Record<"qoder-cn" | "workbuddy" | "workbuddy-ai", IntegrationClientSpec>, opencode: { id: "opencode", // These take `home` explicitly. The export registry's `destination` reads // the real home directory, which is right for telling a user where their // file lives and wrong for a writer that a test must be able to redirect. configPath: (env = process.env, home = homedir()) => opencodeGlobalConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => join(xdgConfigHome(env, home), "opencode"), }, pi: { id: "pi", configPath: (env = process.env, home = homedir()) => piConfigPath(env, home), /* * Deliberately not `piAgentDir` unconditionally. Without an override the * install signal stays `~/.pi`, which is what it has always been: narrowing * it to `~/.pi/agent` would flip a user who has the former without the * latter from installed to absent, and this change is about honoring the * override, not about redefining detection. With an override there is no * parent worth testing — the variable names the agent directory itself — so * that directory becomes the signal. */ detectDir: (env = process.env, home = homedir()) => env.PI_CODING_AGENT_DIR?.trim() ? piAgentDir(env, home) : join(home, ".pi"), }, omp: { id: "omp", configPath: (env = process.env, home = homedir()) => ompModelsConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => ompAgentDir(env, home), sourcePreservingYaml: { path: ["providers", "opencodex"] }, }, hermes: { id: "hermes", configPath: (env = process.env, home = homedir()) => hermesConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => hermesHomeDir(env, home), sourcePreservingYaml: { path: ["providers", "opencodex"] }, }, openclaw: { id: "openclaw", configPath: (env = process.env, home = homedir()) => openclawConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => openclawHomeDir(env, home), }, kimi: { id: "kimi", configPath: (env = process.env, home = homedir()) => kimiConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => kimiHomeDir(env, home), // Kimi reads credentials only from config.toml — it never consults the // environment — so there is no way to point it at a remote bind without // serializing the user's key. }, gajae: { id: "gajae", configPath: (env = process.env, home = homedir()) => gajaeConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => gajaeHomeDir(env, home), }, dsh: { id: "dsh", configPath: (env = process.env, home = homedir()) => dshConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => dshHomeDir(env, home), sourcePreservingYaml: { path: ["llm-pi-ai", "providers", "opencodex"] }, writerLock: { suffix: ".lock" }, /* * DSH 0.1.7+ imports `settings.yaml` once into the first profile that boots * and renames it; what it reads afterwards is the Desktop profile's patch. */ currentStore: { path: (env = process.env, home = homedir()) => dshProfilePatchPath(env, home), format: "yaml", establishes: dshProfilePatchEstablished, buildContribution: buildDshProfilePatchContribution, sourcePreservingYaml: { path: DSH_PROFILE_PROVIDER_PATH }, // DSH's config editor serializes profile edits on the profile manifest's lock. lockFile: store => join(dirname(store), "package.json"), // A Desktop profile manifest without its patch is a profile DSH manages. On each startup // DSH's importLegacyDocument renames `settings.yaml` to `settings.yaml.imported` and imports // it into the active profile, so a block written there would leave opencodex's ownership // record pointing at a file that no longer exists. Refuse it and name the remedy instead. missingStore: { readsStore: (store, statKind) => statKind(join(dirname(store), "package.json")) === "file", emptyDocument: "[]", remedy: "Create it containing `[]` (the empty patch DSH writes for a new profile), then enable the integration again.", }, }, }, mcode: { id: "mcode", configPath: (env = process.env, home = homedir()) => mcodeConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => mcodeHomeDir(env, home), writerLock: { suffix: ".lock" }, }, zcode: { id: "zcode", configPath: (env = process.env, home = homedir(), io) => zcodeConfigPath(env, home, io), detectDir: (env = process.env, home = homedir(), io) => zcodeHomeDir(env, home, io), resolvePaths: (env = process.env, home = homedir(), _context, io) => { let root: string; let pathError: string | undefined; try { root = zcodeHomeDir(env, home, io); } catch (error) { if (!(error instanceof ZcodeSettingsPathError)) throw error; root = zcodeLegacyHomeDir(env, home); pathError = error.message; } // Passing the resolved root prevents a second bootstrap read. An explicit // provider-file override outranks both the setting and ZCODE_DATA_DIR. const storePath = zcodeProviderStorePath({ ...env, ZCODE_DATA_DIR: root }, home, io); return { configPath: join(root, "v2", "config.json"), detectDir: root, storePath, ...(pathError ? { pathError } : {}) }; }, bindsDriftedRecord: (path, env = process.env, home = homedir()) => path === join(zcodeLegacyHomeDir(env, home), "v2", "config.json"), /* * ZCode 3.14 reads its providers from `v2/provider_config.json` and reaches * `v2/config.json` only through the import that seeded it. Where the new * file exists the import is spent, so our write is read by nobody (#5348). */ currentStore: { path: (env = process.env, home = homedir(), io) => zcodeProviderStorePath(env, home, io), format: "json", establishes: zcodeStoreSchemaEstablished, buildContribution: buildZcodeStoreContribution, }, }, commandcode: { id: "commandcode", configPath: (env = process.env, home = homedir()) => commandCodeConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => commandCodeHomeDir(env, home), writerLock: { suffix: ".lock" }, }, prime: { id: "prime", configPath: (env = process.env, home = homedir()) => primeConfigPath(env, home), // The agent directory, not its parent: `PRIME_AGENT_CODING_AGENT_DIR` names // that directory directly, so there is no parent to test when the override // is set. Same choice as OMP, whose detect signal is `ompAgentDir`. detectDir: (env = process.env, home = homedir()) => primeAgentDir(env, home), }, aside: { id: "aside", configPath: (env = process.env, home = homedir()) => asideConfigPath(env, home), /* * The ACCOUNT directory, not `~/.aside`. Aside's CLI creates `~/.aside/cli` * for its own update check before any account exists, so the outer directory * is present on a machine that never signed in, and writing a catalog for an * account that does not exist is worse than reporting absent. */ detectDir: (env = process.env, home = homedir()) => asideAccountDir(env, home), /* * Both paths from ONE account read. The two resolvers above each consult * the account manifest, so a switch landing between them would let an * operation verify one account's install and then write another's catalog. */ resolvePaths: (env = process.env, home = homedir()) => { const detectDir = asideAccountDir(env, home); return { configPath: join(detectDir, "models.json"), detectDir }; }, /* * The account ROOT, with no account under it. Aside writes `accounts.json` * at first launch, so its absence is the ordinary state of an Aside that has * been installed and never signed into -- and a page that answered "cannot * verify" with an empty path for that case named nothing the user could go * look at. */ unresolvedPathHint: (env = process.env, home = homedir()) => join(asideHomeDir(env, home), "u"), }, raycast: { id: "raycast", configPath: (env = process.env, home = homedir()) => raycastConfigPath(env, home), /* * The `ai` directory, not `Raycast.app`. Raycast creates it only when the * user clicks "Reveal Providers Config" in Settings > AI, which is exactly * the signal that Custom Providers is reachable on this install; an app * bundle alone says nothing about the plan or the feature. * * No `sourcePreservingYaml`: that patcher handles block-map leaves only, * and our entry is a SEQUENCE item, so the file is re-rendered through * `renderYaml` (block style). The `[id=opencodex]` selector keeps the user's * other providers in place across that re-render. */ detectDir: (env = process.env, home = homedir()) => raycastAiDir(env, home), }, omo: { id: "omo", configPath: (env = process.env, home = homedir()) => omoConfigPath(env, home), /* * The AGENT directory, not `~/.omo`. The v4 launcher wrapper creates * `~/.omo` to hold `binary-runtime` without ever creating `agent/`, so * detecting on the parent reports an omo v5 install that is not there -- * and `installed` is what stops apply from writing a catalog for an engine * that will never read it. Prime's agent directory and Aside's account * directory are the same shape; Pi's parent-directory check is the odd one. * * No `sourcePreservingYaml` (JSON), no `writerLock` (single writer), and no * `resolvePaths` -- unlike Aside, both omo paths are a pure function of env * and home, so reading them in sequence cannot straddle a state change. */ detectDir: (env = process.env, home = homedir()) => omoAgentDir(env, home), }, cline: { id: "cline", configPath: (env = process.env, home = homedir()) => clineConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => clineSettingsDir(env, home), writerLock: { suffix: ".lock" }, }, kilo: { id: "kilo", configPath: (env = process.env, home = homedir()) => kiloConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => kiloHomeDir(env, home), bindsDriftedRecord: (recordPath, env = process.env, home = homedir()) => KILO_CONFIG_CANDIDATES.some(name => recordPath === kiloCandidatePath(kiloHomeDir(env, home), name)), }, droid: { id: "droid", configPath: (env = process.env, home = homedir()) => droidConfigPath(env, home), detectDir: (env = process.env, home = homedir()) => droidHomeDir(env, home), resolvePaths: (env = process.env, home = homedir(), exportContext) => { const detectDir = droidHomeDir(env, home); assertDroidPathsUnambiguous(detectDir, exportContext); return { configPath: droidConfigPath(env, home), detectDir }; }, }, "gentle-shell": { id: "gentle-shell", configPath: (env, home, io) => gentleShellPaths(env, home, io).configPath, detectDir: (env, home, io) => gentleShellPaths(env, home, io).detectDir, resolvePaths: (env, home, _context, io) => gentleShellPaths(env, home, io), unresolvedPathHint: (_env, home = homedir()) => join(home, ".gentle-shell", "agent", "models.json"), }, t3code: { id: "t3code", configPath: (env = process.env, home = homedir()) => t3codeConfigPath(env, home), // The state directory, not `~/.t3`: the server creates `userdata` on its first start, // while `~/.t3` alone can be left behind by the installer's `bin`. detectDir: (env = process.env, home = homedir()) => join(t3codeHomeDir(env, home), "userdata"), }, }; export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] = Object.keys(INTEGRATION_CLIENTS) as IntegrationClientId[]; /** * The effective config path for a read or mutation, given the ownership record. * * One implementation for status AND the mutation planner: when only one side * carried the binding, the two could disagree again and status would report a * file the writer never touches. Binds only while the client's own * `bindsDriftedRecord` accepts the recorded path (still one of that client's * candidates under the CURRENT env and home) and the file still exists; a * record from another home never binds and keeps its refusal contract. */ export function boundIntegrationConfigPath(input: { clientId: IntegrationClientId; record: { clientId: IntegrationClientId; configPath: string } | null; resolvedPath: string; statKind: (path: string) => string; env?: NodeJS.ProcessEnv; home?: string; }): string { const record = input.record; if ( record && record.clientId === input.clientId && record.configPath !== input.resolvedPath && (input.clientId === "zcode" ? input.statKind(record.configPath) !== "missing" : input.statKind(record.configPath) === "file") && INTEGRATION_CLIENTS[input.clientId].bindsDriftedRecord?.(record.configPath, input.env, input.home) === true ) { return record.configPath; } return input.resolvedPath; } /** * Why a historical restore must not run, or null when it may. * * Kilo keeps one ownership record and may legally have written more than one * candidate. Treating every same-home journaled path as a restore target lets * an undo of an older file commit that file's prior record over the candidate * that owns the integration now. The managed block in the current file stays * on disk, the record points at the old file, and a later disable drops the * record and orphans the newcomer. * * A missing current record is not a collision: undoing the disable that * dropped it still restores the journaled file. A client without * bindsDriftedRecord is unchanged, because that seam is what made the second * candidate a legal target. Direct restore and its preview both ask here, so * they cannot admit different answers. */ export function restoreOwnershipCollision(input: { clientId: IntegrationClientId; journaledPath: string; currentPath: string | null; env?: NodeJS.ProcessEnv; home?: string; }): string | null { const currentPath = input.currentPath; if (currentPath === null || currentPath === input.journaledPath) return null; // A relocated ZCode store must not lose its single record to an older // legacy undo, even when both journaled locations are legal for this home. if (input.clientId === "zcode") { return `that operation was recorded for ${input.journaledPath}, but ${currentPath} currently owns this integration`; } const binds = INTEGRATION_CLIENTS[input.clientId].bindsDriftedRecord; if (!binds) return null; if (binds(input.journaledPath, input.env, input.home) !== true) return null; if (binds(currentPath, input.env, input.home) !== true) return null; return `that operation was recorded for ${input.journaledPath}, but ${currentPath} currently owns this integration`; } export function isIntegrationClientId(value: string): value is IntegrationClientId { return Object.prototype.hasOwnProperty.call(INTEGRATION_CLIENTS, value); }