@creativeintelligence/abbie 0.1.0

package/src/lib/config-sync/adapters/gemini.ts

@@ -0,0 +1,86 @@
+/**
+ * Gemini CLI config adapter.
+ *
+ * Config: ~/.gemini/settings.json
+ * Format: { mcpServers: { "name": { ... } } } inside top-level settings
+ *
+ * Gemini only supports http transport. stdio/sse connections are skipped.
+ * Managed entries use "abbie-{name}" keys.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { ConfigAdapter, ManagedEntry } from "../types.js";
+
+type GeminiMcpEntry = {
+  httpUrl: string;
+  timeout?: number;
+};
+
+type GeminiSettings = {
+  mcpServers?: Record<string, GeminiMcpEntry>;
+  [key: string]: unknown;
+};
+
+export class GeminiConfigAdapter implements ConfigAdapter {
+  readonly agent = "gemini" as const;
+
+  configPath(): string {
+    return join(homedir(), ".gemini", "settings.json");
+  }
+
+  configExists(): boolean {
+    return existsSync(this.configPath());
+  }
+
+  read(): GeminiSettings {
+    if (!this.configExists()) return {};
+    try {
+      return JSON.parse(readFileSync(this.configPath(), "utf-8")) as GeminiSettings;
+    } catch {
+      return {};
+    }
+  }
+
+  merge(
+    current: Record<string, unknown>,
+    managed: ManagedEntry[],
+    previousManagedKeys: string[],
+  ): GeminiSettings {
+    const config = current as GeminiSettings;
+    const servers = { ...(config.mcpServers ?? {}) };
+
+    // Remove previously managed keys
+    for (const key of previousManagedKeys) {
+      delete servers[key];
+    }
+
+    // Add only http-compatible entries (Gemini doesn't support stdio/sse)
+    for (const entry of managed) {
+      const geminiEntry = this.toGeminiEntry(entry);
+      if (geminiEntry) {
+        servers[entry.key] = geminiEntry;
+      }
+    }
+
+    return { ...config, mcpServers: servers };
+  }
+
+  serialize(config: Record<string, unknown>): string {
+    return JSON.stringify(config, null, 2) + "\n";
+  }
+
+  private toGeminiEntry(entry: ManagedEntry): GeminiMcpEntry | null {
+    // Gemini only supports http transport
+    if (entry.transport === "http" && entry.serverUrl) {
+      return { httpUrl: entry.serverUrl };
+    }
+    // SSE can often be used as http — try it
+    if (entry.transport === "sse" && entry.serverUrl) {
+      return { httpUrl: entry.serverUrl };
+    }
+    // Skip stdio — Gemini doesn't support it
+    return null;
+  }
+}

package/src/lib/config-sync/adapters/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Config adapter registry.
+ */
+
+import type { ConfigAdapter, ConfigSyncAgent } from "../types.js";
+import { ClaudeConfigAdapter } from "./claude.js";
+import { CodexConfigAdapter } from "./codex.js";
+import { CopilotConfigAdapter } from "./copilot.js";
+import { GeminiConfigAdapter } from "./gemini.js";
+import { OpencodeConfigAdapter } from "./opencode.js";
+
+const ADAPTERS: ConfigAdapter[] = [
+  new ClaudeConfigAdapter(),
+  new CodexConfigAdapter(),
+  new CopilotConfigAdapter(),
+  new GeminiConfigAdapter(),
+  new OpencodeConfigAdapter(),
+];
+
+/** Get adapter for a specific agent */
+export function getAdapter(agent: ConfigSyncAgent): ConfigAdapter | undefined {
+  return ADAPTERS.find((a) => a.agent === agent);
+}
+
+/** Get all adapters */
+export function getAllAdapters(): ConfigAdapter[] {
+  return ADAPTERS;
+}
+
+/** Get adapters that have config files present */
+export function getActiveAdapters(): ConfigAdapter[] {
+  return ADAPTERS.filter((a) => a.agent !== "opencode" ? true : a.configExists());
+}
+
+export { ClaudeConfigAdapter } from "./claude.js";
+export { CodexConfigAdapter } from "./codex.js";
+export { CopilotConfigAdapter } from "./copilot.js";
+export { GeminiConfigAdapter } from "./gemini.js";
+export { OpencodeConfigAdapter } from "./opencode.js";

package/src/lib/config-sync/adapters/opencode.ts

@@ -0,0 +1,94 @@
+/**
+ * opencode config adapter.
+ *
+ * Unlike other agents, opencode uses CLI commands for MCP management:
+ *   opencode mcp add <name> --transport <type> --url <url>
+ *   opencode mcp remove <name>
+ *
+ * This adapter shells out to the CLI rather than writing config files.
+ * Read/merge/serialize are no-ops — sync is handled via applyChanges().
+ */
+
+import { execSync } from "node:child_process";
+import type { ConfigAdapter, ManagedEntry } from "../types.js";
+
+export class OpencodeConfigAdapter implements ConfigAdapter {
+  readonly agent = "opencode" as const;
+
+  configPath(): string {
+    return "(cli-based)";
+  }
+
+  configExists(): boolean {
+    try {
+      execSync("which opencode", { stdio: "pipe" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  read(): Record<string, unknown> {
+    // No file to read — state managed by opencode CLI
+    return {};
+  }
+
+  merge(
+    _current: Record<string, unknown>,
+    _managed: ManagedEntry[],
+    _previousManagedKeys: string[],
+  ): Record<string, unknown> {
+    // No merge logic — handled by applyChanges
+    return {};
+  }
+
+  serialize(_config: Record<string, unknown>): string {
+    return "";
+  }
+
+  /**
+   * Apply changes via opencode CLI commands.
+   * Removes old managed keys, adds new ones.
+   */
+  applyChanges(managed: ManagedEntry[], previousManagedKeys: string[]): { added: string[]; removed: string[] } {
+    const added: string[] = [];
+    const removed: string[] = [];
+
+    // Remove old managed keys
+    const currentKeys = new Set(managed.map((e) => e.key));
+    for (const key of previousManagedKeys) {
+      if (!currentKeys.has(key)) {
+        try {
+          execSync(`opencode mcp remove ${key}`, { stdio: "pipe", timeout: 10_000 });
+          removed.push(key);
+        } catch {
+          // ignore — may already be removed
+        }
+      }
+    }
+
+    // Add/update current entries
+    for (const entry of managed) {
+      try {
+        // Remove first to ensure clean state
+        try {
+          execSync(`opencode mcp remove ${entry.key}`, { stdio: "pipe", timeout: 10_000 });
+        } catch {
+          // ignore
+        }
+
+        const args = [`opencode mcp add ${entry.key}`];
+        if (entry.transport) args.push(`--transport ${entry.transport}`);
+        if (entry.serverUrl) args.push(`--url ${entry.serverUrl}`);
+        if (entry.command) args.push(`--command ${entry.command}`);
+
+        execSync(args.join(" "), { stdio: "pipe", timeout: 10_000 });
+        added.push(entry.key);
+      } catch {
+        // Skip on failure — don't block other agents
+      }
+    }
+
+    return { added, removed };
+  }
+}

package/src/lib/config-sync/index.ts

@@ -0,0 +1,399 @@
+/**
+ * ConfigSyncRunner — orchestrates Convex → local agent config sync.
+ *
+ * fetch snapshot → compare hash → per-agent merge → atomic write → update manifest
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { getActiveAdapters, getAdapter } from "./adapters/index.js";
+import { OpencodeConfigAdapter } from "./adapters/opencode.js";
+import { createBackup, getSyncDir, writeConfigAtomic } from "./writer.js";
+import type {
+  ConfigSyncAgent,
+  ConfigSyncState,
+  CONFIG_SYNC_AGENTS,
+  ManagedEntry,
+  SidecarManifest,
+  SyncTickResult,
+} from "./types.js";
+
+/** Managed key prefix — entries we own */
+const MANAGED_PREFIX = "abbie-";
+
+/** Default backoff interval (ms) */
+const DEFAULT_INTERVAL_MS = 60_000;
+/** Max backoff on consecutive failures */
+const MAX_BACKOFF_MS = 5 * 60_000;
+/** Circuit breaker threshold */
+const CIRCUIT_BREAKER_FAILURES = 10;
+const CIRCUIT_BREAKER_WINDOW_MS = 10 * 60_000;
+
+type FetchSnapshotFn = () => Promise<{
+  connections: {
+    _id: string;
+    name: string;
+    transport?: string;
+    serverUrl?: string;
+    command?: string;
+    commandArgs?: string[];
+    apiKey?: string;
+    propagateTo?: string[];
+    disabledTools?: string[];
+  }[];
+  revision: number;
+  hash: string;
+}>;
+
+type DecryptFn = (value: string) => Promise<string>;
+
+export type ConfigSyncRunnerOptions = {
+  /** Function to fetch the snapshot from Convex */
+  fetchSnapshot: FetchSnapshotFn;
+  /** Function to decrypt enc_v1: values. If not provided, passes through. */
+  decrypt?: DecryptFn;
+  /** Filter to specific agents (default: all) */
+  agents?: ConfigSyncAgent[];
+};
+
+export class ConfigSyncRunner {
+  private fetchSnapshot: FetchSnapshotFn;
+  private decryptFn: DecryptFn;
+  private agentFilter?: ConfigSyncAgent[];
+  private state: ConfigSyncState;
+  private manifest: SidecarManifest;
+
+  constructor(opts: ConfigSyncRunnerOptions) {
+    this.fetchSnapshot = opts.fetchSnapshot;
+    this.decryptFn = opts.decrypt ?? (async (v) => v);
+    this.agentFilter = opts.agents;
+    this.state = this.loadState();
+    this.manifest = this.loadManifest();
+  }
+
+  /**
+   * Run one sync tick.
+   *
+   * @param opts.force - Skip hash comparison
+   * @param opts.dryRun - Don't write, just report what would change
+   * @param opts.snapshot - Pre-fetched snapshot (from subscription). Skips fetch if provided.
+   */
+  async tick(opts?: {
+    force?: boolean;
+    dryRun?: boolean;
+    snapshot?: Awaited<ReturnType<FetchSnapshotFn>>;
+  }): Promise<SyncTickResult> {
+    const force = opts?.force ?? false;
+    const dryRun = opts?.dryRun ?? false;
+
+    // Circuit breaker check
+    if (this.isCircuitOpen()) {
+      return {
+        ok: false,
+        reason: "circuit-breaker-open",
+        dryRun,
+        changes: [],
+      };
+    }
+
+    let snapshot: Awaited<ReturnType<FetchSnapshotFn>>;
+    if (opts?.snapshot) {
+      snapshot = opts.snapshot;
+    } else {
+      try {
+        snapshot = await this.fetchSnapshot();
+      } catch (err) {
+        this.recordFailure();
+        return {
+          ok: false,
+          reason: `fetch-failed: ${err instanceof Error ? err.message : String(err)}`,
+          dryRun,
+          changes: [],
+        };
+      }
+    }
+
+    // Skip if hash unchanged (unless forced)
+    if (!force && snapshot.hash === this.state.lastHash) {
+      return {
+        ok: true,
+        reason: "unchanged",
+        dryRun,
+        changes: [],
+      };
+    }
+
+    // Build managed entries per agent
+    const entriesByAgent = this.buildEntriesByAgent(snapshot.connections);
+
+    // Decrypt apiKeys
+    for (const entries of Object.values(entriesByAgent)) {
+      for (const entry of entries) {
+        if (entry.apiKey && entry.apiKey.startsWith("enc_v1:")) {
+          try {
+            entry.apiKey = await this.decryptFn(entry.apiKey);
+          } catch {
+            // Leave encrypted — agent won't be able to use it but won't crash
+          }
+        }
+      }
+    }
+
+    // Sync each agent
+    const changes: SyncTickResult["changes"] = [];
+    const adapters = this.agentFilter
+      ? getActiveAdapters().filter((a) => this.agentFilter!.includes(a.agent))
+      : getActiveAdapters();
+
+    for (const adapter of adapters) {
+      const entries = entriesByAgent[adapter.agent] ?? [];
+      const previousKeys = this.manifest[adapter.agent]?.managedKeys ?? [];
+
+      try {
+        // Special handling for opencode (CLI-based)
+        if (adapter instanceof OpencodeConfigAdapter) {
+          if (!adapter.configExists()) {
+            changes.push({
+              agent: adapter.agent,
+              action: "skipped",
+              keysAdded: [],
+              keysRemoved: [],
+              error: "opencode not installed",
+            });
+            continue;
+          }
+
+          if (dryRun) {
+            const currentKeys = new Set(entries.map((e) => e.key));
+            changes.push({
+              agent: adapter.agent,
+              action: entries.length > 0 || previousKeys.length > 0 ? "updated" : "unchanged",
+              keysAdded: entries.map((e) => e.key),
+              keysRemoved: previousKeys.filter((k) => !currentKeys.has(k)),
+            });
+            continue;
+          }
+
+          const result = adapter.applyChanges(entries, previousKeys);
+          changes.push({
+            agent: adapter.agent,
+            action: result.added.length > 0 || result.removed.length > 0 ? "updated" : "unchanged",
+            keysAdded: result.added,
+            keysRemoved: result.removed,
+          });
+
+          // Update manifest
+          this.manifest[adapter.agent] = {
+            configPath: adapter.configPath(),
+            managedKeys: entries.map((e) => e.key),
+            lastSyncHash: snapshot.hash,
+            lastSyncAt: Date.now(),
+          };
+          continue;
+        }
+
+        // Standard file-based adapter
+        const current = adapter.read();
+        const merged = adapter.merge(current, entries, previousKeys);
+        const serialized = adapter.serialize(merged);
+
+        // Compute what changed
+        const currentKeys = new Set(entries.map((e) => e.key));
+        const keysAdded = entries.map((e) => e.key).filter((k) => !previousKeys.includes(k));
+        const keysRemoved = previousKeys.filter((k) => !currentKeys.has(k));
+
+        if (dryRun) {
+          changes.push({
+            agent: adapter.agent,
+            action: keysAdded.length > 0 || keysRemoved.length > 0 ? "updated" : "unchanged",
+            keysAdded,
+            keysRemoved,
+          });
+          continue;
+        }
+
+        // Backup before writing
+        if (adapter.configExists()) {
+          createBackup(adapter.configPath(), adapter.agent);
+        }
+
+        // Atomic write
+        writeConfigAtomic(adapter.configPath(), serialized);
+
+        const hasChanges = keysAdded.length > 0 || keysRemoved.length > 0;
+        changes.push({
+          agent: adapter.agent,
+          action: hasChanges ? "updated" : (adapter.configExists() ? "unchanged" : "created"),
+          keysAdded,
+          keysRemoved,
+        });
+
+        // Update manifest
+        this.manifest[adapter.agent] = {
+          configPath: adapter.configPath(),
+          managedKeys: entries.map((e) => e.key),
+          lastSyncHash: snapshot.hash,
+          lastSyncAt: Date.now(),
+        };
+      } catch (err) {
+        changes.push({
+          agent: adapter.agent,
+          action: "error",
+          keysAdded: [],
+          keysRemoved: [],
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    // Persist state + manifest (unless dry run)
+    if (!dryRun) {
+      this.state.lastHash = snapshot.hash;
+      this.state.lastSuccessAt = Date.now();
+      this.state.consecutiveFailures = 0;
+      this.saveState();
+      this.saveManifest();
+    }
+
+    const hasErrors = changes.some((c) => c.action === "error");
+
+    return {
+      ok: !hasErrors,
+      reason: hasErrors ? "partial-failure" : "synced",
+      dryRun,
+      changes,
+    };
+  }
+
+  /**
+   * Get current state (for status command).
+   */
+  getState(): ConfigSyncState {
+    return { ...this.state };
+  }
+
+  /**
+   * Get current manifest (for status command).
+   */
+  getManifest(): SidecarManifest {
+    return { ...this.manifest };
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────
+
+  /**
+   * Build managed entries grouped by agent, respecting propagateTo.
+   */
+  private buildEntriesByAgent(
+    connections: Awaited<ReturnType<FetchSnapshotFn>>["connections"],
+  ): Record<string, ManagedEntry[]> {
+    const result: Record<string, ManagedEntry[]> = {};
+    const RUNTIME_AGENTS = ["claude", "codex", "copilot", "gemini", "opencode"] as const;
+
+    for (const conn of connections) {
+      const entry: ManagedEntry = {
+        key: `${MANAGED_PREFIX}${conn.name}`,
+        connectionName: conn.name,
+        transport: conn.transport,
+        serverUrl: conn.serverUrl,
+        command: conn.command,
+        commandArgs: conn.commandArgs,
+        apiKey: conn.apiKey,
+        disabledTools: conn.disabledTools,
+      };
+
+      // Determine target agents
+      const targets = conn.propagateTo?.length
+        ? conn.propagateTo.filter((a): a is ConfigSyncAgent =>
+            RUNTIME_AGENTS.includes(a as any),
+          )
+        : [...RUNTIME_AGENTS]; // No propagateTo = all agents
+
+      for (const agent of targets) {
+        if (!result[agent]) result[agent] = [];
+        result[agent].push(entry);
+      }
+    }
+
+    return result;
+  }
+
+  // ─── State persistence ─────────────────────────────────────────────────
+
+  private get statePath(): string {
+    return join(getSyncDir(), "config-sync-state.json");
+  }
+
+  private get manifestPath(): string {
+    return join(getSyncDir(), "managed-sections.json");
+  }
+
+  private loadState(): ConfigSyncState {
+    try {
+      if (existsSync(this.statePath)) {
+        return JSON.parse(readFileSync(this.statePath, "utf-8")) as ConfigSyncState;
+      }
+    } catch {
+      // Start fresh
+    }
+    return {
+      lastHash: "",
+      lastSuccessAt: 0,
+      consecutiveFailures: 0,
+      nextRetryAt: 0,
+    };
+  }
+
+  private saveState(): void {
+    const dir = getSyncDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(this.statePath, JSON.stringify(this.state, null, 2) + "\n");
+  }
+
+  private loadManifest(): SidecarManifest {
+    try {
+      if (existsSync(this.manifestPath)) {
+        return JSON.parse(readFileSync(this.manifestPath, "utf-8")) as SidecarManifest;
+      }
+    } catch {
+      // Start fresh
+    }
+    return {};
+  }
+
+  private saveManifest(): void {
+    const dir = getSyncDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(this.manifestPath, JSON.stringify(this.manifest, null, 2) + "\n");
+  }
+
+  private recordFailure(): void {
+    this.state.consecutiveFailures++;
+    // Exponential backoff
+    const backoffMs = Math.min(
+      DEFAULT_INTERVAL_MS * 2 ** this.state.consecutiveFailures,
+      MAX_BACKOFF_MS,
+    );
+    this.state.nextRetryAt = Date.now() + backoffMs;
+    this.saveState();
+  }
+
+  private isCircuitOpen(): boolean {
+    if (this.state.consecutiveFailures < CIRCUIT_BREAKER_FAILURES) return false;
+    // Check if we're still within the window
+    const windowStart = Date.now() - CIRCUIT_BREAKER_WINDOW_MS;
+    return this.state.nextRetryAt > windowStart;
+  }
+}
+
+export { getAdapter, getAllAdapters, getActiveAdapters } from "./adapters/index.js";
+export { writeConfigAtomic, createBackup, restoreBackup, getLatestBackup, getSyncDir, getBackupsDir } from "./writer.js";
+export type {
+  ConfigAdapter,
+  ConfigSyncAgent,
+  ConfigSyncState,
+  ManagedEntry,
+  SidecarManifest,
+  SyncTickResult,
+} from "./types.js";

package/src/lib/config-sync/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared types for the config sync pipeline.
+ */
+
+/** Agent types that support MCP config sync */
+export const CONFIG_SYNC_AGENTS = ["claude", "codex", "copilot", "gemini", "opencode"] as const;
+export type ConfigSyncAgent = (typeof CONFIG_SYNC_AGENTS)[number];
+
+/** A managed MCP entry to write into an agent config file */
+export type ManagedEntry = {
+  /** Key name in the agent config (prefixed with "abbie-") */
+  key: string;
+  /** Original connection name from Convex */
+  connectionName: string;
+  /** Transport type */
+  transport?: string;
+  /** Server URL for sse/http */
+  serverUrl?: string;
+  /** Command for stdio */
+  command?: string;
+  /** Command args for stdio */
+  commandArgs?: string[];
+  /** API key (decrypted) */
+  apiKey?: string;
+  /** Disabled tools */
+  disabledTools?: string[];
+};
+
+/** Adapter interface — one per agent */
+export interface ConfigAdapter {
+  /** Which agent this adapter handles */
+  agent: ConfigSyncAgent;
+
+  /** Filesystem path to the agent's config file */
+  configPath(): string;
+
+  /** Whether the config file currently exists */
+  configExists(): boolean;
+
+  /** Read and parse the current config file. Returns empty object if missing. */
+  read(): Record<string, unknown>;
+
+  /**
+   * Merge managed entries into the current config.
+   * Must preserve user-defined keys (anything not prefixed with "abbie-").
+   *
+   * @param current - Current parsed config
+   * @param managed - MCP entries to write (all abbie-* keys)
+   * @param previousManagedKeys - Keys from the last sync (for cleanup)
+   * @returns Updated config ready to serialize
+   */
+  merge(
+    current: Record<string, unknown>,
+    managed: ManagedEntry[],
+    previousManagedKeys: string[],
+  ): Record<string, unknown>;
+
+  /** Serialize config to string for writing */
+  serialize(config: Record<string, unknown>): string;
+}
+
+/** Sidecar manifest — tracks which keys abbie manages per agent */
+export type SidecarManifest = {
+  [agent: string]: {
+    configPath: string;
+    managedKeys: string[];
+    lastSyncHash: string;
+    lastSyncAt: number;
+  };
+};
+
+/** Config sync runner state (persisted to disk) */
+export type ConfigSyncState = {
+  lastHash: string;
+  lastSuccessAt: number;
+  consecutiveFailures: number;
+  nextRetryAt: number;
+};
+
+/** Result of a sync tick */
+export type SyncTickResult = {
+  ok: boolean;
+  reason: string;
+  dryRun?: boolean;
+  changes: {
+    agent: ConfigSyncAgent;
+    action: "created" | "updated" | "unchanged" | "skipped" | "error";
+    keysAdded: string[];
+    keysRemoved: string[];
+    error?: string;
+  }[];
+};