mobygate 0.7.2 → 0.8.0

package/lib/connectors/hermes.js

@@ -0,0 +1,186 @@
+/**
+ * Hermes connector.
+ *
+ * Hermes (the agent harness) lives at `~/.hermes/` with a `config.yaml`
+ * holding `model:` (the active model + provider) and `providers:` (a map
+ * of named providers keyed by id). Hermes only speaks the OpenAI-compat
+ * wire format, so we register a single provider entry: `moby`.
+ *
+ * Hermes references custom providers via `model.provider: custom:<id>`,
+ * so wiring "use mobygate as default" means setting:
+ *   model.default:  claude-opus-4-7
+ *   model.provider: custom:moby
+ *
+ * Caveats:
+ *   - We use js-yaml to parse + re-emit. js-yaml does NOT preserve
+ *     comments or blank lines. If the user has hand-edited their YAML
+ *     with comments, those will be lost in the rewritten file. The
+ *     auto-backup (safety.js) catches this — we also warn on detection.
+ *   - We only touch `providers.moby` (always) and `model.*` (only with
+ *     `setDefault: true`). Everything else in the YAML is preserved.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import yaml from 'js-yaml';
+import { backup, writeConfigSafe, diffSummary } from './safety.js';
+import { DEFAULT_BASE_URL, DEFAULT_API_KEY, PROVIDER_NAME_OPENAI } from './index.js';
+
+const HERMES_HOME = process.env.HERMES_HOME || join(homedir(), '.hermes');
+const HERMES_CONFIG = join(HERMES_HOME, 'config.yaml');
+
+function buildProviderEntry({ baseUrl, apiKey }) {
+  return {
+    api: `${baseUrl.replace(/\/$/, '')}/v1`,
+    name: 'Moby (Claude Max via mobygate)',
+    api_key: apiKey,
+    default_model: 'claude-opus-4-7',
+  };
+}
+
+export const hermesConnector = {
+  id: 'hermes',
+  displayName: 'Hermes',
+
+  async detect() {
+    if (!existsSync(HERMES_CONFIG)) return null;
+    let raw;
+    try {
+      raw = readFileSync(HERMES_CONFIG, 'utf8');
+    } catch (e) {
+      return null;
+    }
+    let parsed;
+    try {
+      parsed = yaml.load(raw);
+    } catch (e) {
+      // Config exists but is unparseable — surface that to the user via
+      // detection metadata rather than silently treating as not-installed.
+      return { configPath: HERMES_CONFIG, parseError: e.message };
+    }
+    return {
+      configPath: HERMES_CONFIG,
+      version: parsed?._config_version ?? null,
+      hasComments: /(^|\n)\s*#/.test(raw),
+      parsed,
+    };
+  },
+
+  async inspect() {
+    const det = await this.detect();
+    if (!det) return { installed: false };
+    if (det.parseError) return { installed: true, parseError: det.parseError };
+
+    const providers = det.parsed?.providers || {};
+    const existing = providers[PROVIDER_NAME_OPENAI];
+    const currentDefault = det.parsed?.model?.provider || null;
+    return {
+      installed: true,
+      configPath: det.configPath,
+      mobyProviderExists: !!existing,
+      mobyProviderMatches: existing
+        ? JSON.stringify(existing) === JSON.stringify(buildProviderEntry({
+            baseUrl: existing.api?.replace(/\/v1$/, '') || DEFAULT_BASE_URL,
+            apiKey: existing.api_key,
+          }))
+        : false,
+      currentDefaultProvider: currentDefault,
+      hasComments: det.hasComments,
+    };
+  },
+
+  async plan({ baseUrl = DEFAULT_BASE_URL, apiKey = DEFAULT_API_KEY, setDefault = true } = {}) {
+    const det = await this.detect();
+    if (!det) {
+      return { skip: true, reason: 'Hermes not detected (no ~/.hermes/config.yaml)' };
+    }
+    if (det.parseError) {
+      return { skip: true, reason: `Hermes config is unparseable: ${det.parseError}` };
+    }
+
+    const before = det.parsed || {};
+    const after = JSON.parse(JSON.stringify(before)); // deep clone
+
+    if (!after.providers) after.providers = {};
+    after.providers[PROVIDER_NAME_OPENAI] = buildProviderEntry({ baseUrl, apiKey });
+
+    if (setDefault) {
+      if (!after.model) after.model = {};
+      after.model.default = after.model.default || 'claude-opus-4-7';
+      after.model.provider = `custom:${PROVIDER_NAME_OPENAI}`;
+      after.model.context_length = after.model.context_length || 1000000;
+    }
+
+    const summary = diffSummary(
+      { providers: before.providers, model: before.model },
+      { providers: after.providers,  model: after.model },
+    );
+
+    return {
+      skip: false,
+      configPath: det.configPath,
+      before,
+      after,
+      summary,
+      warnings: det.hasComments
+        ? ['Your config.yaml contains comments. js-yaml will drop them on re-emit. ' +
+           'A timestamped backup is saved before the write — restore from it if needed.']
+        : [],
+    };
+  },
+
+  async apply(plan) {
+    if (plan.skip) return { applied: false, reason: plan.reason };
+    // js-yaml emit options: quote strings that need it, but use block
+    // style for maps (keeps it readable, matches Hermes's existing style).
+    const yamlOut = yaml.dump(plan.after, {
+      indent: 2,
+      lineWidth: 0,
+      noRefs: true,
+      sortKeys: false,
+    });
+    const result = writeConfigSafe(plan.configPath, yamlOut);
+    return {
+      applied: true,
+      configPath: result.path,
+      backupPath: result.backupPath,
+      bytesWritten: result.bytesWritten,
+    };
+  },
+
+  async disconnect() {
+    const det = await this.detect();
+    if (!det) return { applied: false, reason: 'Hermes not installed' };
+    if (det.parseError) return { applied: false, reason: `parse error: ${det.parseError}` };
+    const before = det.parsed || {};
+    const after = JSON.parse(JSON.stringify(before));
+    let changed = false;
+
+    if (after.providers && after.providers[PROVIDER_NAME_OPENAI]) {
+      delete after.providers[PROVIDER_NAME_OPENAI];
+      changed = true;
+    }
+    // Reset default provider if it was pointing at us.
+    if (after.model?.provider === `custom:${PROVIDER_NAME_OPENAI}`) {
+      // Don't pick a replacement — leave it for the user to re-set.
+      // Better than silently switching them to anthropic-direct (which
+      // would burn API tokens) or whatever else we'd guess.
+      after.model.provider = 'anthropic';
+      changed = true;
+    }
+
+    if (!changed) return { applied: false, reason: 'No moby provider entry in Hermes config' };
+
+    const yamlOut = yaml.dump(after, { indent: 2, lineWidth: 0, noRefs: true, sortKeys: false });
+    const result = writeConfigSafe(det.configPath, yamlOut);
+    return {
+      applied: true,
+      configPath: result.path,
+      backupPath: result.backupPath,
+      note: after.model?.provider === 'anthropic'
+        ? 'Reset model.provider to "anthropic" — verify ANTHROPIC_TOKEN is set if you intend to use direct API.'
+        : null,
+    };
+  },
+};

package/lib/connectors/index.js

@@ -0,0 +1,80 @@
+/**
+ * Client connector registry + orchestrator.
+ *
+ * Connectors auto-wire third-party clients (Hermes, OpenClaw, etc.) to
+ * use mobygate as their inference provider. This avoids the manual
+ * "find your client's config file → paste this JSON snippet → restart"
+ * dance for each client a user wants to connect.
+ *
+ * Each connector lives in `lib/connectors/<id>.js` and exports a
+ * uniform contract:
+ *
+ *   - id            — short stable identifier (e.g. 'hermes', 'openclaw')
+ *   - displayName   — human-readable name for prompts/logs
+ *   - detect()      — probe for the client; returns DetectionResult | null
+ *   - inspect()     — read current config; returns InspectionResult
+ *   - plan(opts)    — compute the diff to apply; returns Plan
+ *   - apply(plan)   — perform the modification atomically
+ *   - disconnect()  — remove our entries cleanly
+ *
+ * Branding: all provider entries we register use the `moby` prefix to
+ * make them visually identifiable. Two flavors:
+ *   - `moby`        — OpenAI-compat surface (POST /v1/chat/completions)
+ *   - `moby-native` — Anthropic-messages surface (POST /v1/messages)
+ *
+ * Clients that only handle one wire format get whichever fits; clients
+ * that handle both get both registered, with `moby-native` as the
+ * preferred default.
+ */
+
+import { hermesConnector } from './hermes.js';
+import { openclawConnector } from './openclaw.js';
+
+// Public API for any caller that wants to know where mobygate is reachable.
+// Defaults match server.js's defaults; init can override via opts.
+export const DEFAULT_BASE_URL = 'http://127.0.0.1:3456';
+export const DEFAULT_API_KEY  = 'claude-max';
+
+// Branded provider names. Short, distinct, unmistakably from mobygate.
+export const PROVIDER_NAME_OPENAI    = 'moby';
+export const PROVIDER_NAME_ANTHROPIC = 'moby-native';
+
+/**
+ * All registered connectors, in display order. Add new ones here.
+ * v0.8.0 ships with hermes + openclaw; pi-agent and others are on the
+ * v0.8.x backlog.
+ */
+export const CONNECTORS = [
+  hermesConnector,
+  openclawConnector,
+];
+
+/**
+ * Run detection across every registered connector. Returns an array of
+ * { connector, detection } where detection is the connector's
+ * DetectionResult (or null if not found). Connectors that throw are
+ * treated as "not detected" — we never let one broken adapter break
+ * the whole orchestrator.
+ */
+export async function detectAll() {
+  const out = [];
+  for (const c of CONNECTORS) {
+    let detection = null;
+    try {
+      detection = await c.detect();
+    } catch (e) {
+      // Detection should be silent on failure — the client may simply
+      // not be installed. Don't surface noise.
+      detection = null;
+    }
+    out.push({ connector: c, detection });
+  }
+  return out;
+}
+
+/**
+ * Convenience: get a connector by id, or null.
+ */
+export function getConnector(id) {
+  return CONNECTORS.find((c) => c.id === id) || null;
+}

package/lib/connectors/openclaw.js

@@ -0,0 +1,253 @@
+/**
+ * OpenClaw connector.
+ *
+ * OpenClaw is the Discord-bot agent harness. Its config lives at
+ * `~/.openclaw/openclaw.json` (canonical on Linux/Mac, mirrored as
+ * `%USERPROFILE%\.openclaw\openclaw.json` on Windows — verified
+ * against a real Geekom install).
+ *
+ * Unlike Hermes, OpenClaw understands BOTH wire formats — `openai-completions`
+ * (for legacy OpenAI-shape providers) and `anthropic-messages` (for
+ * Anthropic-native providers, which unlocks vision + native tools +
+ * thinking blocks). So we register both surfaces:
+ *   - moby         (api: openai-completions  → /v1/chat/completions)
+ *   - moby-native  (api: anthropic-messages  → /v1/messages)
+ *
+ * `moby-native` is set as the main + default model when setDefault is
+ * true — that's the wire format that gives OpenClaw the full feature
+ * set. `moby` stays available as fallback / OpenAI-compat clients.
+ *
+ * Config schema (inferred from the user's Geekom config):
+ *   {
+ *     "models": {
+ *       "main":     "<provider>/<model-id>",
+ *       "default":  "<provider>/<model-id>",
+ *       "providers": {
+ *         "<provider-id>": {
+ *           "baseUrl": "...",
+ *           "apiKey":  "...",
+ *           "api":     "openai-completions" | "anthropic-messages",
+ *           "models":  [ { id, name, contextWindow, maxTokens, input, reasoning, cost }, ... ]
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { writeConfigSafe, diffSummary } from './safety.js';
+import {
+  DEFAULT_BASE_URL,
+  DEFAULT_API_KEY,
+  PROVIDER_NAME_OPENAI,
+  PROVIDER_NAME_ANTHROPIC,
+} from './index.js';
+
+const OPENCLAW_HOME = process.env.OPENCLAW_HOME || join(homedir(), '.openclaw');
+const OPENCLAW_CONFIG = join(OPENCLAW_HOME, 'openclaw.json');
+
+// Probe order — first match wins. Lets us support installs that put the
+// config somewhere other than ~/.openclaw/.
+const CONFIG_PROBES = [
+  OPENCLAW_CONFIG,
+  // Add other plausible paths here as they're discovered. Empty list is
+  // fine for v0.8.0 — every install we've seen uses ~/.openclaw/.
+];
+
+const MODELS_OPENAI_SURFACE = [
+  { id: 'claude-opus-4-7',   name: 'Claude Opus 4.7 (Max via Moby)',   contextWindow: 1000000, maxTokens: 32768, input: ['text'],          reasoning: false, cost: { input: 0, output: 0 } },
+  { id: 'claude-opus-4-6',   name: 'Claude Opus 4.6 (Max via Moby)',   contextWindow: 200000,  maxTokens: 16384, input: ['text'],          reasoning: false, cost: { input: 0, output: 0 } },
+  { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6 (Max via Moby)', contextWindow: 200000,  maxTokens: 16384, input: ['text'],          reasoning: false, cost: { input: 0, output: 0 } },
+  { id: 'claude-haiku-4-5',  name: 'Claude Haiku 4.5 (Max via Moby)',  contextWindow: 200000,  maxTokens: 16384, input: ['text'],          reasoning: false, cost: { input: 0, output: 0 } },
+];
+
+// Native surface declares text+image input and reasoning capability so
+// OpenClaw will send vision content and surface thinking blocks.
+const MODELS_NATIVE_SURFACE = [
+  { id: 'claude-opus-4-7',   name: 'Claude Opus 4.7 (Max, native)',   contextWindow: 1000000, maxTokens: 32768, input: ['text', 'image'], reasoning: true,  cost: { input: 0, output: 0 } },
+  { id: 'claude-opus-4-6',   name: 'Claude Opus 4.6 (Max, native)',   contextWindow: 200000,  maxTokens: 16384, input: ['text', 'image'], reasoning: true,  cost: { input: 0, output: 0 } },
+  { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6 (Max, native)', contextWindow: 200000,  maxTokens: 16384, input: ['text', 'image'], reasoning: true,  cost: { input: 0, output: 0 } },
+  { id: 'claude-haiku-4-5',  name: 'Claude Haiku 4.5 (Max, native)',  contextWindow: 200000,  maxTokens: 16384, input: ['text', 'image'], reasoning: true,  cost: { input: 0, output: 0 } },
+];
+
+function buildOpenAIProvider({ baseUrl, apiKey }) {
+  return {
+    baseUrl,
+    apiKey,
+    api: 'openai-completions',
+    models: MODELS_OPENAI_SURFACE,
+  };
+}
+
+function buildNativeProvider({ baseUrl, apiKey }) {
+  return {
+    baseUrl,
+    apiKey,
+    api: 'anthropic-messages',
+    models: MODELS_NATIVE_SURFACE,
+  };
+}
+
+function findConfigPath() {
+  for (const p of CONFIG_PROBES) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+function isMobyDefaultPointer(s) {
+  if (typeof s !== 'string') return false;
+  return s.startsWith(`${PROVIDER_NAME_OPENAI}/`) || s.startsWith(`${PROVIDER_NAME_ANTHROPIC}/`);
+}
+
+export const openclawConnector = {
+  id: 'openclaw',
+  displayName: 'OpenClaw',
+
+  async detect() {
+    const configPath = findConfigPath();
+    if (!configPath) return null;
+    let raw;
+    try {
+      raw = readFileSync(configPath, 'utf8');
+    } catch (e) {
+      return null;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      return { configPath, parseError: e.message };
+    }
+    return { configPath, parsed };
+  },
+
+  async inspect() {
+    const det = await this.detect();
+    if (!det) return { installed: false };
+    if (det.parseError) return { installed: true, parseError: det.parseError };
+
+    const providers = det.parsed?.models?.providers || {};
+    return {
+      installed: true,
+      configPath: det.configPath,
+      mobyProviderExists: !!providers[PROVIDER_NAME_OPENAI],
+      mobyNativeProviderExists: !!providers[PROVIDER_NAME_ANTHROPIC],
+      currentMain: det.parsed?.models?.main || null,
+      currentDefault: det.parsed?.models?.default || null,
+    };
+  },
+
+  async plan({
+    baseUrl = DEFAULT_BASE_URL,
+    apiKey = DEFAULT_API_KEY,
+    setDefault = true,
+    registerOpenAISurface = true,
+    registerNativeSurface = true,
+  } = {}) {
+    const det = await this.detect();
+    if (!det) {
+      return { skip: true, reason: 'OpenClaw not detected (no ~/.openclaw/openclaw.json)' };
+    }
+    if (det.parseError) {
+      return { skip: true, reason: `OpenClaw config is unparseable JSON: ${det.parseError}` };
+    }
+
+    const before = det.parsed || {};
+    const after = JSON.parse(JSON.stringify(before)); // deep clone
+
+    if (!after.models)            after.models = {};
+    if (!after.models.providers)  after.models.providers = {};
+
+    if (registerOpenAISurface) {
+      after.models.providers[PROVIDER_NAME_OPENAI] = buildOpenAIProvider({ baseUrl, apiKey });
+    }
+    if (registerNativeSurface) {
+      after.models.providers[PROVIDER_NAME_ANTHROPIC] = buildNativeProvider({ baseUrl, apiKey });
+    }
+
+    if (setDefault) {
+      // Prefer native if registered; fall back to openai-compat otherwise.
+      const preferredProvider = registerNativeSurface
+        ? PROVIDER_NAME_ANTHROPIC
+        : registerOpenAISurface
+          ? PROVIDER_NAME_OPENAI
+          : null;
+      if (preferredProvider) {
+        const target = `${preferredProvider}/claude-opus-4-7`;
+        after.models.main = target;
+        after.models.default = target;
+      }
+    }
+
+    const summary = diffSummary(
+      { providers: before.models?.providers, main: before.models?.main, default: before.models?.default },
+      { providers: after.models.providers,  main: after.models.main,  default: after.models.default },
+    );
+
+    return {
+      skip: false,
+      configPath: det.configPath,
+      before,
+      after,
+      summary,
+      warnings: [],
+    };
+  },
+
+  async apply(plan) {
+    if (plan.skip) return { applied: false, reason: plan.reason };
+    // OpenClaw uses 2-space indented JSON in its own config writes.
+    // Match that style so subsequent self-writes don't reformat the
+    // whole file.
+    const jsonOut = JSON.stringify(plan.after, null, 2) + '\n';
+    const result = writeConfigSafe(plan.configPath, jsonOut);
+    return {
+      applied: true,
+      configPath: result.path,
+      backupPath: result.backupPath,
+      bytesWritten: result.bytesWritten,
+    };
+  },
+
+  async disconnect() {
+    const det = await this.detect();
+    if (!det) return { applied: false, reason: 'OpenClaw not installed' };
+    if (det.parseError) return { applied: false, reason: `parse error: ${det.parseError}` };
+    const before = det.parsed || {};
+    const after = JSON.parse(JSON.stringify(before));
+    let changed = false;
+
+    const providers = after.models?.providers;
+    if (providers) {
+      for (const name of [PROVIDER_NAME_OPENAI, PROVIDER_NAME_ANTHROPIC]) {
+        if (providers[name]) { delete providers[name]; changed = true; }
+      }
+    }
+    // If main/default was pointing at us, blank them — let the user
+    // re-pick rather than guess at a replacement.
+    if (isMobyDefaultPointer(after.models?.main)) {
+      after.models.main = null;
+      changed = true;
+    }
+    if (isMobyDefaultPointer(after.models?.default)) {
+      after.models.default = null;
+      changed = true;
+    }
+
+    if (!changed) return { applied: false, reason: 'No moby provider entries in OpenClaw config' };
+
+    const jsonOut = JSON.stringify(after, null, 2) + '\n';
+    const result = writeConfigSafe(det.configPath, jsonOut);
+    return {
+      applied: true,
+      configPath: result.path,
+      backupPath: result.backupPath,
+      note: (after.models?.main === null || after.models?.default === null)
+        ? 'Reset main/default model to null — set a new model in OpenClaw before next request.'
+        : null,
+    };
+  },
+};

package/lib/connectors/safety.js

@@ -0,0 +1,124 @@
+/**
+ * Safety primitives for connector adapters.
+ *
+ * Every connector that modifies a third-party config file goes through
+ * these helpers — they enforce backup, atomic write, and a couple of
+ * sanity guards. Adapters MUST NOT call writeFileSync directly on a
+ * user's config; they MUST go through `writeConfigSafe`.
+ *
+ * The contract:
+ *   1. Always back up first to `<file>.mobygate-backup-<ISO-timestamp>`.
+ *   2. Write to a temp file in the same directory, fsync, then rename.
+ *      Atomic rename on POSIX, near-atomic on Windows (NTFS handles it
+ *      transparently for same-volume renames).
+ *   3. Verify the rename produced the expected content (read-back +
+ *      length sanity check) before declaring success.
+ *
+ * This keeps a corrupt file or partial write from destroying a user's
+ * carefully-tuned client config.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  copyFileSync,
+  existsSync,
+  statSync,
+  mkdirSync,
+  unlinkSync,
+} from 'fs';
+import { dirname, basename, join } from 'path';
+
+const ISO_SAFE = (d = new Date()) => d.toISOString().replace(/[:.]/g, '-');
+
+/**
+ * Make a timestamped backup of `path`. Returns the backup path.
+ * No-op (returns null) if `path` doesn't exist — this lets adapters
+ * call `backup()` unconditionally even when they're creating a new file.
+ */
+export function backup(path) {
+  if (!existsSync(path)) return null;
+  const dir = dirname(path);
+  const name = basename(path);
+  const backupPath = join(dir, `${name}.mobygate-backup-${ISO_SAFE()}`);
+  copyFileSync(path, backupPath);
+  return backupPath;
+}
+
+/**
+ * Atomically write `content` to `path`. Backs up first. Returns
+ * `{ path, backupPath, bytesWritten }` on success; throws on any failure
+ * (the original file is preserved by the backup).
+ *
+ * `content` must be a string. Adapters that work in structured formats
+ * (YAML, JSON) serialize before calling this.
+ */
+export function writeConfigSafe(path, content) {
+  if (typeof content !== 'string') {
+    throw new Error(`writeConfigSafe: content must be a string (got ${typeof content})`);
+  }
+  if (content.length === 0) {
+    throw new Error(`writeConfigSafe: refusing to write empty content to ${path}`);
+  }
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const backupPath = backup(path);
+  const tempPath = `${path}.mobygate-tmp-${ISO_SAFE()}`;
+
+  try {
+    writeFileSync(tempPath, content, 'utf8');
+    // Sanity check: the temp file should be the size we just wrote.
+    const size = statSync(tempPath).size;
+    if (size === 0) throw new Error('temp file is empty after write');
+    renameSync(tempPath, path);
+  } catch (e) {
+    // Best-effort cleanup of the temp file. If rename failed mid-flight
+    // (rare), the original is intact via the backup.
+    try { if (existsSync(tempPath)) unlinkSync(tempPath); } catch {}
+    throw new Error(`writeConfigSafe failed for ${path}: ${e.message}` +
+                    (backupPath ? ` (original preserved at ${backupPath})` : ''));
+  }
+
+  // Final verify: read back what's on disk and confirm it matches.
+  const onDisk = readFileSync(path, 'utf8');
+  if (onDisk !== content) {
+    throw new Error(`writeConfigSafe verify failed for ${path}: ` +
+                    `read-back differs from intended content` +
+                    (backupPath ? ` (original preserved at ${backupPath})` : ''));
+  }
+
+  return { path, backupPath, bytesWritten: Buffer.byteLength(content, 'utf8') };
+}
+
+/**
+ * Compute a human-readable summary of a planned change. Used by adapters
+ * to produce dry-run output. `before` and `after` are arbitrary objects;
+ * we don't try to be clever — just a count of top-level differences.
+ *
+ * Returns lines like:
+ *   + providers.moby (added)
+ *   ~ providers.moby-native (changed)
+ *   - providers.old-thing (removed)
+ */
+export function diffSummary(before, after, prefix = '') {
+  const lines = [];
+  const beforeKeys = new Set(Object.keys(before || {}));
+  const afterKeys  = new Set(Object.keys(after  || {}));
+  for (const k of afterKeys) {
+    const fullKey = prefix ? `${prefix}.${k}` : k;
+    if (!beforeKeys.has(k)) {
+      lines.push(`+ ${fullKey} (added)`);
+    } else if (JSON.stringify(before[k]) !== JSON.stringify(after[k])) {
+      lines.push(`~ ${fullKey} (changed)`);
+    }
+  }
+  for (const k of beforeKeys) {
+    if (!afterKeys.has(k)) {
+      const fullKey = prefix ? `${prefix}.${k}` : k;
+      lines.push(`- ${fullKey} (removed)`);
+    }
+  }
+  return lines;
+}