npm - mobygate - Versions diffs - 0.7.3 → 0.8.1 - Mend

mobygate 0.7.3 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/CHANGELOG.md +180 -0
package/bin/mobygate.js +292 -12
package/index.html +1 -0
package/inspector.html +422 -0
package/lib/anthropic.js +23 -0
package/lib/connectors/hermes.js +188 -0
package/lib/connectors/index.js +80 -0
package/lib/connectors/openclaw.js +290 -0
package/lib/connectors/safety.js +141 -0
package/lib/request-capture.js +394 -0
package/package.json +2 -1
package/server.js +248 -6

package/inspector.html ADDED Viewed

@@ -0,0 +1,422 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>mobygate — inspector</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700&family=VT323&display=swap" rel="stylesheet">
+  <style>
+    :root {
+      --bg: #0B0B09;
+      --bg-2: #14140F;
+      --bg-3: #1F1F17;
+      --fg: #F3EFE4;
+      --muted: #5A5F54;
+      --dim: #8A8F84;
+      --accent: #B7E56D;
+      --warn: #F1B05A;
+      --crit: #E66B5C;
+      --hit: #6CC994;
+      --border: #2A2A1F;
+    }
+    * { box-sizing: border-box; }
+    html, body { margin: 0; padding: 0; background: var(--bg); color: var(--fg); font-family: 'JetBrains Mono', ui-monospace, Menlo, monospace; font-size: 13px; height: 100vh; overflow: hidden; }
+    .display { font-family: 'VT323', monospace; letter-spacing: 0.02em; }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    button { font-family: inherit; font-size: inherit; }
+    pre, code { font-family: 'JetBrains Mono', ui-monospace, monospace; }
+    header {
+      display: flex; align-items: center; gap: 16px;
+      padding: 12px 20px; border-bottom: 1px solid var(--border);
+      background: var(--bg-2);
+    }
+    header .title { font-size: 28px; line-height: 1; color: var(--accent); }
+    header .breadcrumb { color: var(--dim); font-size: 12px; }
+    header .spacer { flex: 1; }
+    header .toggle {
+      display: flex; align-items: center; gap: 8px;
+      padding: 6px 12px; border: 1px solid var(--border);
+      background: var(--bg-3); cursor: pointer; color: var(--fg);
+    }
+    header .toggle.on { border-color: var(--accent); color: var(--accent); }
+    header .toggle .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--muted); }
+    header .toggle.on .dot { background: var(--accent); animation: pulse 1.8s infinite; }
+    @keyframes pulse { 0%,100%{opacity:1} 50%{opacity:.4} }
+    .layout { display: grid; grid-template-columns: 460px 1fr; height: calc(100vh - 53px); }
+    .list-pane { border-right: 1px solid var(--border); overflow-y: auto; background: var(--bg); }
+    .list-stats { padding: 10px 16px; color: var(--dim); font-size: 11px; border-bottom: 1px solid var(--border); }
+    .row {
+      padding: 10px 16px; border-bottom: 1px solid var(--border);
+      cursor: pointer; transition: background .1s;
+    }
+    .row:hover { background: var(--bg-2); }
+    .row.active { background: var(--bg-3); border-left: 3px solid var(--accent); padding-left: 13px; }
+    .row .r1 { display: flex; gap: 8px; align-items: baseline; margin-bottom: 4px; }
+    .row .r1 .ts { color: var(--dim); font-size: 11px; }
+    .row .r1 .path { color: var(--fg); font-size: 12px; }
+    .row .r1 .path.native { color: var(--accent); }
+    .row .r2 { color: var(--dim); font-size: 11px; display: flex; gap: 12px; flex-wrap: wrap; }
+    .row .r2 .pill { padding: 1px 6px; background: var(--bg-3); border-radius: 2px; }
+    .row .r2 .hit { color: var(--hit); }
+    .row .r2 .nohit { color: var(--warn); }
+    .detail-pane { overflow-y: auto; padding: 20px 28px; }
+    .detail-pane.empty { display: flex; align-items: center; justify-content: center; color: var(--dim); }
+    .stat-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 12px; margin-bottom: 24px; }
+    .stat {
+      padding: 12px 14px; border: 1px solid var(--border); background: var(--bg-2);
+    }
+    .stat .label { color: var(--dim); font-size: 10px; text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 4px; }
+    .stat .val { color: var(--fg); font-family: 'VT323', monospace; font-size: 24px; line-height: 1; }
+    .stat .val.accent { color: var(--accent); }
+    .stat .val.warn { color: var(--warn); }
+    .stat .val.crit { color: var(--crit); }
+    .stat .sub { color: var(--dim); font-size: 11px; margin-top: 2px; }
+    .section { margin-bottom: 24px; }
+    .section h3 { color: var(--accent); font-size: 12px; margin: 0 0 10px; text-transform: uppercase; letter-spacing: 0.05em; }
+    .sys-block {
+      padding: 8px 12px; margin-bottom: 4px;
+      border-left: 2px solid var(--border); background: var(--bg-2);
+      font-size: 11px;
+    }
+    .sys-block.cached { border-left-color: var(--hit); }
+    .sys-block .head { color: var(--dim); margin-bottom: 4px; }
+    .sys-block .head .marker { color: var(--hit); margin-left: 8px; }
+    .sys-block .preview { color: var(--fg); white-space: pre-wrap; max-height: 80px; overflow: hidden; opacity: 0.7; }
+    .msg-row { padding: 6px 0; border-bottom: 1px solid var(--border); display: grid; grid-template-columns: 40px 80px 70px 1fr; gap: 12px; align-items: center; font-size: 11px; }
+    .msg-row .idx { color: var(--dim); text-align: right; }
+    .msg-row .role { padding: 1px 6px; background: var(--bg-3); text-align: center; }
+    .msg-row .role.user { color: #88B4FF; }
+    .msg-row .role.assistant { color: var(--accent); }
+    .msg-row .role.tool { color: var(--warn); }
+    .msg-row .role.system { color: var(--crit); }
+    .msg-row .bytes { color: var(--dim); text-align: right; }
+    .msg-row .preview { color: var(--fg); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; opacity: 0.85; }
+    .msg-row.cached { background: rgba(108, 201, 148, 0.04); }
+    .tool-list { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; }
+    .tool { padding: 6px 10px; background: var(--bg-2); border: 1px solid var(--border); font-size: 11px; }
+    .usage-grid { display: grid; grid-template-columns: 2fr 1fr 1fr 1fr; gap: 8px; font-size: 11px; }
+    .usage-grid > div { padding: 8px 12px; background: var(--bg-2); border: 1px solid var(--border); }
+    .usage-grid .label { color: var(--dim); text-transform: uppercase; letter-spacing: 0.05em; font-size: 10px; }
+    .usage-grid .val { color: var(--fg); font-size: 18px; font-family: 'VT323', monospace; line-height: 1; margin-top: 4px; }
+    .usage-grid .val.hit { color: var(--hit); }
+    .usage-grid .val.dim { color: var(--dim); }
+    .placeholder { color: var(--dim); font-size: 12px; padding: 16px; text-align: center; }
+    /* Scrollbar */
+    ::-webkit-scrollbar { width: 8px; height: 8px; }
+    ::-webkit-scrollbar-track { background: var(--bg); }
+    ::-webkit-scrollbar-thumb { background: var(--border); }
+    ::-webkit-scrollbar-thumb:hover { background: var(--muted); }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="title display">mobygate :: inspector</div>
+    <div class="breadcrumb">~/.mobygate/captures/</div>
+    <div class="spacer"></div>
+    <button id="toggle" class="toggle">
+      <span class="dot"></span>
+      <span id="toggle-label">capture: ?</span>
+    </button>
+    <a href="/">← dashboard</a>
+  </header>
+  <div class="layout">
+    <div class="list-pane" id="list-pane">
+      <div class="list-stats" id="list-stats">loading…</div>
+      <div id="list"></div>
+    </div>
+    <div class="detail-pane empty" id="detail">
+      <div>Select a capture from the left to inspect.</div>
+    </div>
+  </div>
+  <script>
+    let selectedFilename = null;
+    let captureCache = []; // last fetch result, used to compute deltas
+    // ──────────── helpers ────────────
+    const esc = (s) => String(s ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+    const fmt = (n) => Number(n || 0).toLocaleString();
+    const fmtBytes = (b) => {
+      if (b < 1024) return b + ' B';
+      if (b < 1024*1024) return (b/1024).toFixed(1) + ' KB';
+      return (b/(1024*1024)).toFixed(1) + ' MB';
+    };
+    const fmtTime = (ms) => {
+      const d = new Date(ms);
+      return d.toLocaleTimeString('en-US', { hour12: false });
+    };
+    // ──────────── capture toggle ────────────
+    async function refreshToggleState() {
+      try {
+        const r = await fetch('/dashboard/captures-state');
+        const s = await r.json();
+        const btn = document.getElementById('toggle');
+        const lbl = document.getElementById('toggle-label');
+        btn.classList.toggle('on', !!s.enabled);
+        lbl.textContent = 'capture: ' + (s.enabled ? 'ON' : 'off') + (s.envVar ? ' (env)' : '');
+      } catch {}
+    }
+    document.getElementById('toggle').addEventListener('click', async () => {
+      const cur = document.getElementById('toggle').classList.contains('on');
+      try {
+        await fetch('/dashboard/captures-toggle', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ enabled: !cur }),
+        });
+        refreshToggleState();
+      } catch {}
+    });
+    // ──────────── list rendering ────────────
+    async function refreshList() {
+      try {
+        const r = await fetch('/dashboard/captures?limit=200');
+        const data = await r.json();
+        captureCache = data.captures || [];
+        renderList(captureCache, data);
+      } catch (e) {
+        document.getElementById('list-stats').textContent = 'failed: ' + e.message;
+      }
+    }
+    function renderList(captures, meta) {
+      const stats = document.getElementById('list-stats');
+      if (!captures.length) {
+        stats.textContent = 'no captures yet — toggle capture on and send a request';
+        document.getElementById('list').innerHTML = '';
+        return;
+      }
+      stats.textContent = `${captures.length} captures · ${meta.total} total`;
+      const html = captures.map(c => {
+        const isNative = c.path === '/v1/messages';
+        const hitClass = c.cacheHitPct == null ? '' : (parseFloat(c.cacheHitPct) > 50 ? 'hit' : 'nohit');
+        const hitText = c.cacheHitPct == null ? 'no resp yet' : `${c.cacheHitPct}% cache`;
+        const sel = c.filename === selectedFilename ? ' active' : '';
+        return `<div class="row${sel}" data-fn="${esc(c.filename)}">
+          <div class="r1">
+            <span class="ts">${fmtTime(c.ts)}</span>
+            <span class="path${isNative ? ' native' : ''}">${esc(c.path)}</span>
+            <span class="ts" style="margin-left:auto">${esc(c.model || '')}</span>
+          </div>
+          <div class="r2">
+            <span class="pill">${c.msgCount} msgs</span>
+            <span class="pill">${fmt(c.grandTokens)} tok</span>
+            <span class="pill ${hitClass}">${hitText}</span>
+            ${c.cacheControlSystem ? `<span class="pill">sys-cache ${esc(c.cacheControlSystem)}</span>` : ''}
+          </div>
+        </div>`;
+      }).join('');
+      document.getElementById('list').innerHTML = html;
+      // Wire row clicks
+      document.querySelectorAll('.row').forEach(el => {
+        el.addEventListener('click', () => loadDetail(el.dataset.fn));
+      });
+    }
+    // ──────────── detail rendering ────────────
+    async function loadDetail(filename) {
+      selectedFilename = filename;
+      document.querySelectorAll('.row').forEach(r => r.classList.toggle('active', r.dataset.fn === filename));
+      const detail = document.getElementById('detail');
+      detail.classList.remove('empty');
+      detail.innerHTML = `<div class="placeholder">loading ${esc(filename)}…</div>`;
+      try {
+        const r = await fetch('/dashboard/captures/' + encodeURIComponent(filename));
+        const data = await r.json();
+        renderDetail(data);
+      } catch (e) {
+        detail.innerHTML = `<div class="placeholder">failed: ${esc(e.message)}</div>`;
+      }
+    }
+    function renderDetail({ filename, body, summary }) {
+      const sysBlocks = Array.isArray(body.system) ? body.system : (typeof body.system === 'string' ? [{ type: 'text', text: body.system }] : []);
+      const msgs = body.messages || [];
+      const tools = body.tools || [];
+      const sysBytes = sysBlocks.reduce((a, b) => a + (b?.text?.length || 0), 0);
+      const msgBytes = msgs.reduce((a, m) => {
+        if (typeof m.content === 'string') return a + m.content.length;
+        if (Array.isArray(m.content)) return a + m.content.reduce((aa, b) => aa + (b?.text?.length || 0) + (b?.input ? JSON.stringify(b.input).length : 0) + (typeof b?.content === 'string' ? b.content.length : 0), 0);
+        return a;
+      }, 0);
+      const toolBytes = JSON.stringify(tools).length;
+      const grand = sysBytes + msgBytes + toolBytes;
+      // Pull response stats out of the appended summary text
+      const grab = (re) => { const m = summary.match(re); return m ? m[1].trim() : null; };
+      const inputUncached = parseInt(grab(/input_tokens \(uncached\):\s+(\d+)/) || '0', 10);
+      const cacheRead = parseInt(grab(/cache_read_input_tokens:\s+(\d+)/) || '0', 10);
+      const cacheCreate = parseInt(grab(/cache_creation_input_tokens:\s+(\d+)/) || '0', 10);
+      const outputTokens = parseInt(grab(/output_tokens:\s+(\d+)/) || '0', 10);
+      const cacheHit = grab(/cache hit rate:\s+([\d.]+)%/);
+      const savings = grab(/savings from cache:\s+([\d.]+)%/);
+      const duration = grab(/duration:\s+(\d+) ms/);
+      const sysHtml = sysBlocks.length === 0
+        ? '<div class="placeholder">no system block</div>'
+        : sysBlocks.map((b, i) => {
+            const cached = !!b.cache_control;
+            const preview = (b.text || '').slice(0, 600);
+            return `<div class="sys-block${cached ? ' cached' : ''}">
+              <div class="head">[${i}] ${esc(b.type || '?')} · ${fmt((b.text||'').length)} bytes${cached ? `<span class="marker">cache_control: ${esc(JSON.stringify(b.cache_control))}</span>` : ''}</div>
+              <div class="preview">${esc(preview)}${(b.text||'').length > 600 ? '…' : ''}</div>
+            </div>`;
+          }).join('');
+      const msgHtml = msgs.length > 60
+        ? renderTrimmedMessages(msgs)
+        : msgs.map((m, i) => renderMessageRow(m, i)).join('');
+      const toolsHtml = tools.length === 0
+        ? '<div class="placeholder">no tools declared</div>'
+        : `<div class="tool-list">${tools.map(t => {
+            const name = t.name || t.function?.name || '(unnamed)';
+            return `<div class="tool">${esc(name)}</div>`;
+          }).join('')}</div>`;
+      const usageHtml = (cacheRead + cacheCreate + inputUncached + outputTokens === 0)
+        ? '<div class="placeholder">response not captured yet (request still in flight, or capture was off when response landed)</div>'
+        : `<div class="usage-grid">
+            <div>
+              <div class="label">cache hit rate</div>
+              <div class="val hit">${cacheHit || '0'}%</div>
+              <div class="label" style="margin-top:6px">savings</div>
+              <div class="val ${parseFloat(savings)>50?'hit':''}" style="font-size:14px">${savings || '0'}%</div>
+            </div>
+            <div>
+              <div class="label">input (uncached)</div>
+              <div class="val">${fmt(inputUncached)}</div>
+            </div>
+            <div>
+              <div class="label">cache read</div>
+              <div class="val hit">${fmt(cacheRead)}</div>
+            </div>
+            <div>
+              <div class="label">cache create</div>
+              <div class="val ${cacheCreate>0?'':'dim'}">${fmt(cacheCreate)}</div>
+              <div class="label" style="margin-top:6px">output</div>
+              <div class="val" style="font-size:14px">${fmt(outputTokens)}</div>
+            </div>
+          </div>`;
+      document.getElementById('detail').innerHTML = `
+        <div class="stat-grid">
+          <div class="stat">
+            <div class="label">model</div>
+            <div class="val accent">${esc(body.model || '?')}</div>
+            <div class="sub">${body.stream ? 'streaming' : 'sync'} · ${duration ? duration + ' ms' : '—'}</div>
+          </div>
+          <div class="stat">
+            <div class="label">messages</div>
+            <div class="val">${msgs.length}</div>
+            <div class="sub">${fmtBytes(msgBytes)}</div>
+          </div>
+          <div class="stat">
+            <div class="label">total wire</div>
+            <div class="val">${fmt(Math.round(grand/4))}</div>
+            <div class="sub">~tokens · ${fmtBytes(grand)}</div>
+          </div>
+          <div class="stat">
+            <div class="label">system block</div>
+            <div class="val ${sysBlocks.some(b=>b.cache_control)?'accent':'warn'}">${fmtBytes(sysBytes)}</div>
+            <div class="sub">${sysBlocks.length} block(s) · ${sysBlocks.filter(b=>b.cache_control).length} cached</div>
+          </div>
+        </div>
+        <div class="section">
+          <h3>Response usage</h3>
+          ${usageHtml}
+        </div>
+        <div class="section">
+          <h3>System blocks</h3>
+          ${sysHtml}
+        </div>
+        <div class="section">
+          <h3>Messages timeline (${msgs.length})</h3>
+          ${msgHtml}
+        </div>
+        <div class="section">
+          <h3>Tools (${tools.length})</h3>
+          ${toolsHtml}
+        </div>
+        <div class="section">
+          <h3>Raw summary</h3>
+          <pre style="background:var(--bg-2);padding:12px;border:1px solid var(--border);font-size:11px;color:var(--dim);white-space:pre-wrap;max-height:300px;overflow:auto">${esc(summary)}</pre>
+        </div>
+      `;
+    }
+    function renderMessageRow(m, i) {
+      const role = m.role || '?';
+      const cached = Array.isArray(m.content) && m.content.some(b => b?.cache_control);
+      let preview = '';
+      let bytes = 0;
+      if (typeof m.content === 'string') {
+        preview = m.content.slice(0, 200);
+        bytes = m.content.length;
+      } else if (Array.isArray(m.content)) {
+        const parts = m.content.map(b => {
+          if (b?.type === 'text') return b.text || '';
+          if (b?.type === 'tool_use') return `🔧 ${b.name || '?'}(${JSON.stringify(b.input || {}).slice(0, 80)})`;
+          if (b?.type === 'tool_result') {
+            const tc = Array.isArray(b.content) ? (b.content.find(x => x.type === 'text')?.text || '') : (b.content || '');
+            return `← ${String(tc).slice(0, 100)}`;
+          }
+          if (b?.type === 'image') return '🖼️ [image]';
+          return JSON.stringify(b).slice(0, 80);
+        });
+        preview = parts.join(' · ').slice(0, 250);
+        bytes = m.content.reduce((a, b) => a + (b?.text?.length || 0) + (b?.input ? JSON.stringify(b.input).length : 0) + (typeof b?.content === 'string' ? b.content.length : 0), 0);
+      }
+      return `<div class="msg-row${cached ? ' cached' : ''}">
+        <span class="idx">${i}</span>
+        <span class="role ${role}">${role}</span>
+        <span class="bytes">${fmtBytes(bytes)}</span>
+        <span class="preview">${esc(preview)}${cached ? ' 🔒' : ''}</span>
+      </div>`;
+    }
+    function renderTrimmedMessages(msgs) {
+      // Show first 5 and last 10 for long conversations
+      const head = msgs.slice(0, 5).map((m, i) => renderMessageRow(m, i)).join('');
+      const tail = msgs.slice(-10).map((m, i) => renderMessageRow(m, msgs.length - 10 + i)).join('');
+      return head + `<div class="placeholder">… ${msgs.length - 15} messages collapsed …</div>` + tail;
+    }
+    // ──────────── kickoff ────────────
+    refreshToggleState();
+    refreshList();
+    setInterval(() => { refreshList(); refreshToggleState(); }, 3000);
+  </script>
+</body>
+</html>

package/lib/anthropic.js CHANGED Viewed

@@ -27,6 +27,29 @@
 import { v4 as uuidv4 } from 'uuid';
+// ---------------------------------------------------------------------------
+// SDK usage extraction
+// ---------------------------------------------------------------------------
+/**
+ * Pulls the full token usage from an SDK 'result' message — defensive
+ * against shape variations (the Claude Agent SDK sometimes nests these
+ * under `.usage`, sometimes places them flat on the message). Returns
+ * a complete usage shape with cache_read / cache_creation fields zeroed
+ * out if absent. Used by the 4 mobygate handlers to populate response
+ * captures and dashboard cache-hit metrics.
+ */
+export function extractSdkUsage(message) {
+  if (!message) return { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 };
+  const u = message.usage || message;
+  return {
+    input_tokens: u.input_tokens || 0,
+    output_tokens: u.output_tokens || 0,
+    cache_read_input_tokens: u.cache_read_input_tokens || 0,
+    cache_creation_input_tokens: u.cache_creation_input_tokens || 0,
+  };
+}
 // ---------------------------------------------------------------------------
 // Content extraction — read individual block types out of an Anthropic message
 // ---------------------------------------------------------------------------

package/lib/connectors/hermes.js ADDED Viewed

@@ -0,0 +1,188 @@
+/**
+ * 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: !result.unchanged,
+      unchanged: !!result.unchanged,
+      reason: result.unchanged ? 'config already up-to-date (byte-identical)' : null,
+      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,
+    };
+  },
+};