@iislee/opencodex 2.11.0 → 2.31.0

package/src/integrations/omp-yaml-source.ts

@@ -0,0 +1,358 @@
+/**
+ * Source-preserving mutation for one plain block-map YAML fragment.
+ *
+ * Shared client settings are not ours to re-render. This scanner accepts only
+ * the small, unambiguous source shape we can patch byte-for-byte around the
+ * owned leaf. Every candidate is parsed again and compared with the complete
+ * expected document; unsupported YAML fails closed and never falls back to a
+ * whole-document serializer.
+ */
+import { renderYaml } from "./serialize";
+
+interface SourceLine {
+  start: number;
+  end: number;
+  body: string;
+}
+
+interface LocatedEntry {
+  lines: readonly SourceLine[];
+  index: number;
+  indent: number;
+  endIndex: number;
+}
+
+interface MissingEntry {
+  lines: readonly SourceLine[];
+  missingDepth: number;
+  indent: number;
+  insertAt: number;
+}
+
+type LocatedPath = { kind: "existing"; entry: LocatedEntry } | { kind: "missing"; entry: MissingEntry };
+
+export type YamlFragmentMutation =
+  | { kind: "upsert"; value: unknown }
+  | { kind: "remove"; createdContainers: readonly string[] };
+
+export type OmpYamlMutation =
+  | { kind: "upsert"; value: unknown }
+  | { kind: "remove"; removeEmptyProviders: boolean };
+
+function sourceLines(text: string): SourceLine[] {
+  const lines: SourceLine[] = [];
+  const matcher = /[^\r\n]*(?:\r\n|\n|$)/gu;
+  for (const match of text.matchAll(matcher)) {
+    const raw = match[0];
+    if (raw.length === 0) continue;
+    const start = match.index;
+    const body = raw.endsWith("\r\n")
+      ? raw.slice(0, -2)
+      : raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+    lines.push({ start, end: start + raw.length, body });
+  }
+  return lines;
+}
+
+function leadingSpaces(line: string): number | null {
+  const leading = line.match(/^[ \t]*/u)?.[0] ?? "";
+  return leading.includes("\t") ? null : leading.length;
+}
+
+function isBlank(line: string): boolean {
+  return line.trim().length === 0;
+}
+
+function isComment(line: string): boolean {
+  return line.trimStart().startsWith("#");
+}
+
+function hasInlineComment(line: string): boolean {
+  return line.includes("#");
+}
+
+function regexpEscape(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function isPlainBlockKey(line: string, indent: number, key: string): boolean {
+  const spaces = leadingSpaces(line);
+  if (spaces !== indent) return false;
+  const rest = line.slice(indent);
+  return new RegExp(`^${regexpEscape(key)}:[ ]*(?:#.*)?$`, "u").test(rest);
+}
+
+function containerEnd(lines: readonly SourceLine[], start: number, indent: number): number | null {
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const body = lines[index]!.body;
+    const spaces = leadingSpaces(body);
+    if (spaces === null) return null;
+    if (isBlank(body)) continue;
+    if (isComment(body)) {
+      if (spaces <= indent) return index;
+      continue;
+    }
+    if (spaces <= indent) return index;
+  }
+  return lines.length;
+}
+
+function childEnd(
+  lines: readonly SourceLine[],
+  start: number,
+  parentEnd: number,
+  indent: number,
+): number | null {
+  for (let index = start + 1; index < parentEnd; index += 1) {
+    const body = lines[index]!.body;
+    const spaces = leadingSpaces(body);
+    if (spaces === null) return null;
+    // Blank lines and same-level comments remain outside our replacement.
+    // Deeper comments belong to the leaf and would be destroyed, so refuse.
+    if (isBlank(body)) return index;
+    if (isComment(body)) return spaces <= indent ? index : null;
+    if (spaces <= indent) return index;
+    if (hasInlineComment(body)) return null;
+  }
+  return parentEnd;
+}
+
+function canonicalValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, child]) => [key, canonicalValue(child)]),
+    );
+  }
+  return value;
+}
+
+function semanticallyMatches(text: string, expected: unknown): boolean {
+  try {
+    const parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+    return JSON.stringify(canonicalValue(parsed)) === JSON.stringify(canonicalValue(expected));
+  } catch {
+    return false;
+  }
+}
+
+function lineEnding(text: string): "\n" | "\r\n" {
+  return text.includes("\r\n") ? "\r\n" : "\n";
+}
+
+function readPath(doc: unknown, path: readonly string[]): unknown {
+  let cursor = doc;
+  for (const key of path) {
+    if (cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) return undefined;
+    cursor = (cursor as Record<string, unknown>)[key];
+    if (cursor === undefined) return undefined;
+  }
+  return cursor;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function immediateIndent(
+  lines: readonly SourceLine[],
+  start: number,
+  end: number,
+  parentIndent: number,
+): number | null {
+  let indent: number | null = null;
+  for (let index = start; index < end; index += 1) {
+    const body = lines[index]!.body;
+    const spaces = leadingSpaces(body);
+    if (spaces === null) return null;
+    if (isBlank(body) || isComment(body) || spaces <= parentIndent) continue;
+    indent = indent === null ? spaces : Math.min(indent, spaces);
+  }
+  return indent ?? parentIndent + 2;
+}
+
+/** Locate a path only when every present segment is a plain block-map key. */
+function locatePath(text: string, parsed: unknown, path: readonly string[]): LocatedPath | null {
+  if (path.length === 0 || !isPlainRecord(parsed)) return null;
+  const lines = sourceLines(text);
+  if (lines.some(line => leadingSpaces(line.body) === null)) return null;
+
+  let rangeStart = 0;
+  let rangeEnd = lines.length;
+  let parentIndent = -2;
+  const prefix: string[] = [];
+  for (let depth = 0; depth < path.length; depth += 1) {
+    const indent = depth === 0 ? 0 : immediateIndent(lines, rangeStart, rangeEnd, parentIndent);
+    if (indent === null) return null;
+    const matches: number[] = [];
+    for (let index = rangeStart; index < rangeEnd; index += 1) {
+      if (isPlainBlockKey(lines[index]!.body, indent, path[depth]!)) matches.push(index);
+    }
+    if (matches.length > 1) return null;
+    prefix.push(path[depth]!);
+    if (matches.length === 0) {
+      // The parser saw this key through syntax we do not patch (quoted/flow,
+      // merge aliases, or an ambiguous indentation shape).
+      if (readPath(parsed, prefix) !== undefined) return null;
+      const insertAt = rangeEnd < lines.length ? lines[rangeEnd]!.start : text.length;
+      return { kind: "missing", entry: { lines, missingDepth: depth, indent, insertAt } };
+    }
+
+    const index = matches[0]!;
+    const end = containerEnd(lines, index, indent);
+    if (end === null) return null;
+    if (depth === path.length - 1) {
+      if (hasInlineComment(lines[index]!.body)) return null;
+      const leafEnd = childEnd(lines, index, end, indent);
+      if (leafEnd === null) return null;
+      return { kind: "existing", entry: { lines, index, indent, endIndex: leafEnd } };
+    }
+    if (!isPlainRecord(readPath(parsed, prefix))) return null;
+    rangeStart = index + 1;
+    rangeEnd = end;
+    parentIndent = indent;
+  }
+  return null;
+}
+
+function nestedValue(path: readonly string[], value: unknown): Record<string, unknown> {
+  let nested: unknown = value;
+  for (let index = path.length - 1; index >= 0; index -= 1) nested = { [path[index]!]: nested };
+  return nested as Record<string, unknown>;
+}
+
+function rendered(value: unknown, indent: number, eol: "\n" | "\r\n"): string {
+  return renderYaml(value as Record<string, unknown>, indent).replaceAll("\n", eol);
+}
+
+function preserveFinalNewline(candidate: string, original: string, eol: "\n" | "\r\n"): string {
+  if (original.length > 0 && !original.endsWith("\n") && candidate.endsWith(eol)) {
+    return candidate.slice(0, -eol.length);
+  }
+  return candidate;
+}
+
+function upsertSource(
+  text: string,
+  parsed: unknown,
+  path: readonly string[],
+  value: unknown,
+): string | null {
+  const located = locatePath(text, parsed, path);
+  if (located === null) return null;
+  const eol = lineEnding(text);
+  if (located.kind === "existing") {
+    const { lines, index, indent, endIndex } = located.entry;
+    const startOffset = lines[index]!.start;
+    const endOffset = endIndex < lines.length ? lines[endIndex]!.start : text.length;
+    const candidate = `${text.slice(0, startOffset)}${rendered({ [path[path.length - 1]!]: value }, indent, eol)}${text.slice(endOffset)}`;
+    return preserveFinalNewline(candidate, text, eol);
+  }
+
+  const { missingDepth, indent, insertAt } = located.entry;
+  const prefix = insertAt > 0 && !text.slice(0, insertAt).endsWith("\n") ? eol : "";
+  const insertion = rendered(nestedValue(path.slice(missingDepth), value), indent, eol);
+  const candidate = `${text.slice(0, insertAt)}${prefix}${insertion}${text.slice(insertAt)}`;
+  return preserveFinalNewline(candidate, text, eol);
+}
+
+function removeExactPath(text: string, path: readonly string[], requireEmpty: boolean): string | null {
+  let parsed: unknown;
+  try {
+    parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+  } catch {
+    return null;
+  }
+  const located = locatePath(text, parsed, path);
+  if (located === null || located.kind !== "existing") return null;
+  const { lines, index, endIndex } = located.entry;
+  const startOffset = lines[index]!.start;
+  const endOffset = endIndex < lines.length ? lines[endIndex]!.start : text.length;
+  if (requireEmpty) {
+    const sourceBody = text.slice(lines[index]!.end, endOffset);
+    if (sourceBody.trim().length > 0) return null;
+  }
+  return `${text.slice(0, startOffset)}${text.slice(endOffset)}`;
+}
+
+function planSourceRemoval(
+  text: string,
+  path: readonly string[],
+  createdContainers: readonly string[],
+): { text: string; prunedContainers: string[] } | null {
+  let next = removeExactPath(text, path, false);
+  if (next === null) return null;
+  const created = new Set(createdContainers);
+  const prunedContainers: string[] = [];
+  for (let depth = path.length - 1; depth >= 1; depth -= 1) {
+    const containerPath = path.slice(0, depth);
+    const encoded = containerPath.join("\u0000");
+    if (!created.has(encoded)) continue;
+    const pruned = removeExactPath(next, containerPath, true);
+    // A user-added sibling/comment makes this ancestor source-owned now. Keep
+    // it (and every parent) while still removing our leaf.
+    if (pruned === null) break;
+    next = pruned;
+    prunedContainers.push(encoded);
+  }
+  return { text: next, prunedContainers };
+}
+
+/** Containers whose source ranges are still empty and safe to prune. */
+export function sourcePrunableYamlContainers(
+  text: string,
+  path: readonly string[],
+  createdContainers: readonly string[],
+): readonly string[] | null {
+  return planSourceRemoval(text, path, createdContainers)?.prunedContainers ?? null;
+}
+
+function removeSource(
+  text: string,
+  path: readonly string[],
+  createdContainers: readonly string[],
+): string | null {
+  return planSourceRemoval(text, path, createdContainers)?.text ?? null;
+}
+
+/**
+ * Patch one arbitrary plain block-map path, preserving every other byte.
+ */
+export function patchYamlFragmentSource(
+  text: string,
+  path: readonly string[],
+  mutation: YamlFragmentMutation,
+  expected: unknown,
+): string | null {
+  let parsed: unknown;
+  try {
+    parsed = text.trim().length === 0 ? {} : Bun.YAML.parse(text);
+  } catch {
+    return null;
+  }
+  const patched = mutation.kind === "upsert"
+    ? upsertSource(text, parsed, path, mutation.value)
+    : removeSource(text, path, mutation.createdContainers);
+  return patched !== null && semanticallyMatches(patched, expected) ? patched : null;
+}
+
+/** Backward-compatible OMP wrapper around the generic path patcher. */
+export function patchOmpYamlSource(
+  text: string,
+  mutation: OmpYamlMutation,
+  expected: unknown,
+): string | null {
+  return patchYamlFragmentSource(
+    text,
+    ["providers", "opencodex"],
+    mutation.kind === "upsert"
+      ? mutation
+      : {
+          kind: "remove",
+          createdContainers: mutation.removeEmptyProviders ? ["providers"] : [],
+        },
+    expected,
+  );
+}

package/src/integrations/owned-refresh.ts

@@ -0,0 +1,74 @@
+/**
+ * Refresh a file integration only when OpenCodex already owns its block.
+ *
+ * This is the safe bridge between an implicit operation such as `ocx sync`
+ * and the explicit integration writer. An implicit sync may update a block
+ * the user previously enabled, but it must never claim an unowned block,
+ * recreate one the user removed, or overwrite edits made after our write.
+ */
+import type { ExportModel } from "../clients/config-export";
+import type { OcxConfig } from "../types";
+import type { IntegrationIO } from "./config-io";
+import type { IntegrationClientId } from "./registry";
+import { runIntegrationMutationFlight } from "./mutation-flight";
+import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
+import {
+  refreshIntegrationCoordinated,
+  type CoordinatedIntegrationOptions,
+} from "./writer";
+
+export interface OwnedIntegrationRefreshInput {
+  clientId: IntegrationClientId;
+  /** Lazy in `ocx sync`, so an unowned client does not even load the catalog. */
+  models: readonly ExportModel[] | (() => Promise<readonly ExportModel[]>);
+  config: OcxConfig;
+  port: number;
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  store?: IntegrationStateStore;
+  io?: IntegrationIO;
+}
+
+export interface OwnedIntegrationRefreshOutcome {
+  readonly client: IntegrationClientId;
+  readonly ok: boolean;
+  readonly changed?: boolean;
+  readonly reason?: string;
+}
+
+/**
+ * Returns `null` when the client has never been connected by OpenCodex.
+ * Callers use that distinction to report "left alone" rather than "skipped".
+ */
+export async function refreshOwnedIntegration(
+  input: OwnedIntegrationRefreshInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<OwnedIntegrationRefreshOutcome | null> {
+  const store = input.store ?? createIntegrationStateStore();
+
+  // The ownership record is the user's durable opt-in. Do this check before
+  // reading or classifying the target so an implicit sync can never turn an
+  // unowned provider block into one of ours.
+  const record = store.readRecords()[input.clientId];
+  if (!record || record.clientId !== input.clientId) return null;
+
+  const { models: suppliedModels, ...rest } = input;
+  const models = typeof suppliedModels === "function"
+    ? await suppliedModels()
+    : suppliedModels;
+  const bound = { ...rest, models, store };
+  const result = await runIntegrationMutationFlight(
+    input.clientId,
+    "refresh",
+    input.io?.now ?? Date.now,
+    () => refreshIntegrationCoordinated(bound, options),
+  );
+  return result.ok
+    ? {
+        client: input.clientId,
+        ok: true,
+        changed: result.changed,
+        ...(result.state === "absent" ? { reason: result.message } : {}),
+      }
+    : { client: input.clientId, ok: false, reason: result.message };
+}

package/src/integrations/ownership.ts

@@ -0,0 +1,111 @@
+/**
+ * What opencodex remembers about a client between operations.
+ *
+ * Two hashes, because the two questions are genuinely independent: the FILE
+ * hash identifies the exact result for restore and for clients whose writer
+ * re-serializes the whole document. The BLOCK hash identifies OMP's surgically
+ * patched fragment and detects catalog drift. One hash cannot safely answer
+ * both questions in a shared client config.
+ *
+ * Design of record: devlog/_fin/260802_client_toggle_api/021 §2.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ManagedContribution, ManagedFragment } from "../clients/config-export";
+import { atomicWriteFile, getConfigDir } from "../config";
+import type { IntegrationClientId } from "./registry";
+
+/** 16 hex chars — the same shape as the Claude Desktop applied fingerprint. */
+export function fingerprint(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+/**
+ * Canonical bytes of a contribution. Fragments are sorted by path so two builds
+ * of the same contribution hash identically regardless of emission order.
+ */
+export function canonicalContribution(contribution: ManagedContribution): string {
+  const sorted = [...contribution.fragments].sort((a, b) => {
+    const left = a.path.join("\u0000");
+    const right = b.path.join("\u0000");
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+  return JSON.stringify(sorted.map(fragment => [fragment.path, fragment.value]));
+}
+
+export interface OwnershipRecord {
+  clientId: IntegrationClientId;
+  configPath: string;
+  /** Hash of the WHOLE file as we left it — protects whole-file restore. */
+  fileFingerprint: string;
+  /** Hash of our contribution — detects catalog/port drift. */
+  blockFingerprint: string;
+  /** The exact paths we own. Removal touches these and nothing else. */
+  fragmentPaths: readonly (readonly string[])[];
+  /**
+   * Containers this apply had to CREATE, `\0`-joined.
+   *
+   * Kimi's `models` map exists only because our aliases need somewhere to
+   * live. Without this, disable left it behind as an empty container in a file
+   * the user never asked us to restructure — while a `providers: {}` the user
+   * wrote themselves must survive. Optional because records written before
+   * this field existed simply prune nothing, which is the old behavior.
+   */
+  createdContainers?: readonly string[];
+  appliedAt: string;
+  opId: string;
+}
+
+/**
+ * The integrations directory itself. Every primitive takes THIS path, never a
+ * config root, so a caller cannot accidentally produce
+ * `<root>/integrations/integrations` by passing an already-resolved value.
+ */
+export function integrationsDir(configDir: string = getConfigDir()): string {
+  return join(configDir, "integrations");
+}
+
+/** `atomicWriteFile` does not create parents. */
+export function ensureDir(filePath: string): void {
+  mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+}
+
+function recordsPath(dir: string): string {
+  return join(dir, "records.json");
+}
+
+export function readRecords(
+  dir: string = integrationsDir(),
+): Partial<Record<IntegrationClientId, OwnershipRecord>> {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(recordsPath(dir), "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Partial<Record<IntegrationClientId, OwnershipRecord>>;
+    }
+  } catch {
+    // Missing or corrupt records mean "we remember nothing", which the
+    // classifier reads as a conflict for an existing block. Fail closed: an
+    // unreadable memory is never permission to delete.
+  }
+  return {};
+}
+
+export function writeRecord(record: OwnershipRecord, dir: string = integrationsDir()): void {
+  const all = readRecords(dir);
+  all[record.clientId] = record;
+  ensureDir(recordsPath(dir));
+  atomicWriteFile(recordsPath(dir), `${JSON.stringify(all, null, 2)}\n`);
+}
+
+export function deleteRecord(clientId: IntegrationClientId, dir: string = integrationsDir()): void {
+  const all = readRecords(dir);
+  if (!(clientId in all)) return;
+  delete all[clientId];
+  ensureDir(recordsPath(dir));
+  atomicWriteFile(recordsPath(dir), `${JSON.stringify(all, null, 2)}\n`);
+}
+
+export function fragmentPathsOf(contribution: ManagedContribution): readonly (readonly string[])[] {
+  return contribution.fragments.map((fragment: ManagedFragment) => fragment.path);
+}

package/src/integrations/registry.ts

@@ -0,0 +1,159 @@
+/**
+ * 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 { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  EXPORT_CLIENTS,
+  dshConfigPath,
+  dshHomeDir,
+  gajaeConfigPath,
+  gajaeHomeDir,
+  hermesConfigPath,
+  hermesHomeDir,
+  kimiConfigPath,
+  kimiHomeDir,
+  mcodeConfigPath,
+  mcodeHomeDir,
+  ompAgentDir,
+  ompModelsConfigPath,
+  opencodeGlobalConfigPath,
+  openclawConfigPath,
+  openclawHomeDir,
+  piAgentDir,
+  piConfigPath,
+  primeAgentDir,
+  primeConfigPath,
+  zcodeConfigPath,
+  zcodeHomeDir,
+  type ExportClientId,
+} 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 IntegrationClientSpec {
+  id: IntegrationClientId;
+  /** The client's config file, honoring that client's own environment override. */
+  configPath: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  /** Directory whose existence is the cheap "is it installed?" signal. */
+  detectDir: (env?: NodeJS.ProcessEnv, home?: string) => 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" };
+}
+
+/**
+ * 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> = {
+  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),
+  },
+  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" },
+  },
+  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()) => zcodeConfigPath(env, home),
+    detectDir: (env = process.env, home = homedir()) => zcodeHomeDir(env, home),
+  },
+  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),
+  },
+};
+
+export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =
+  Object.keys(INTEGRATION_CLIENTS) as IntegrationClientId[];
+
+export function isIntegrationClientId(value: string): value is IntegrationClientId {
+  return Object.prototype.hasOwnProperty.call(INTEGRATION_CLIENTS, value);
+}