mobygate 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -4,6 +4,178 @@ All notable changes to mobygate are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version numbers are
 [Semantic Versioning](https://semver.org/).
 
+## [0.8.2] — 2026-04-28
+
+Multi-agent fixes. Found the day after v0.8.1 shipped, while testing
+three OpenClaw bots (Mobius/Lux/Mercury) in parallel on the same
+machine. Both bugs were invisible without the v0.8.1 inspector.
+
+### Fixed
+
+- **Session-key collision when multiple agents share a boilerplate
+  prefix in their system prompt.** v0.7.1's auto-derive hashed the
+  first 500 characters of the system prompt; OpenClaw's "You are a
+  personal assistant running inside OpenClaw…" preamble fills more
+  than that, so the per-agent personality content (loaded later from
+  workspace SOUL.md / IDENTITY.md / etc.) didn't reach the hash. Two
+  separate agents (Lux on sonnet-4-6, Mercury on sonnet-4-6) collided
+  onto the same auto-key when given the same first user message
+  ("@Lux @Mercury Hi"). Same key → same SDK session reuse → cache
+  thrash and potential session-state mixing.
+
+  Bumped `SYSTEM_TRIM` from 500 → 20000 chars. Verified against real
+  captured request bodies that collided in v0.8.1 — they now hash to
+  distinct keys (`auto_b0371e5c…` vs `auto_2b90afd7…`).
+
+  SHA-256 cost on 20kB is ~10-20µs per request, irrelevant in the
+  hot path.
+
+- **Model map silently downgraded `claude-sonnet-4-6` to retired
+  `claude-sonnet-4-5-20250929`.** When the v0.8.0 model map was
+  written, the Claude Agent SDK didn't recognize the un-dated
+  `claude-sonnet-4-6` alias and we worked around it by routing to the
+  most recent dated 4-5. The SDK has since added native 4-6 support,
+  but mobygate kept the workaround in place. Result: clients (OpenClaw
+  Lux/Mercury) configured for sonnet-4-6 were having their requests
+  rewritten to the retired 4-5-20250929 dated id. Anthropic accepted
+  the call but the response wasn't billing into the user's "Sonnet
+  only" quota — it was showing 0% used despite live traffic. Likely
+  Claude was falling back internally to opus or returning a
+  zero-billed degraded response.
+
+  Fix: route `claude-sonnet-4-6` through directly. Also updated
+  `claude-sonnet-4` and the `sonnet` shorthand to point at 4-6
+  (current latest) instead of the retired dated 4-5 entry. Explicit
+  `claude-sonnet-4-5` requests still route to the dated id for
+  backward compatibility.
+
+  Discovery: the inspector showed Lux/Mercury captures all stamped
+  with `model: claude-sonnet-4-6` (correct from the request side) but
+  Anthropic's quota panel reported 0% sonnet usage. The server.log's
+  `model=claude-sonnet-4-6 → claude-sonnet-4-5-20250929` translation
+  line was the smoking gun.
+
+### Notes
+
+The proper long-term fix is for clients to pass an explicit
+`X-Session-Id` header per agent (mobygate has supported this since
+v0.7.1 — it always wins over auto-derive). This bump is a defensive
+measure for clients that don't.
+
+Discovery flow is a nice validation of the v0.8.1 inspector: the
+collision was invisible at the OpenClaw level (each bot's replies
+arrived correctly because OpenClaw maintains its own per-agent SDK
+state) but jumped out as soon as the captures were sorted by session
+key in the inspector — two different model requests with the same
+session-key, with bootstrap text 55kB long but identical first 500
+chars. Without the inspector, this would have surfaced as
+unpredictable cache hit rates and been blamed on Anthropic.
+
+## [0.8.1] — 2026-04-27
+
+Diagnostic visibility release. Adds a request/response capture system,
+a session inspector UI, a `mobygate tail` CLI, and fixes the v0.8.0
+connector idempotency bug. Born out of an OpenClaw debugging session
+where it took an hour of forensics to discover OpenClaw was using
+OpenAI shape (no cache_control) instead of `/v1/messages` — a one-line
+config flip — because mobygate had no visibility into what its
+upstream clients were actually sending.
+
+### Added
+
+- **Request/response capture system** (`lib/request-capture.js`).
+  - Off by default. Three ways to enable:
+    1. Env var: `MOBY_CAPTURE=1 mobygate start`
+    2. Touch file: `touch ~/.mobygate/.capture-enabled` (survives
+       restarts, dashboard-toggleable)
+    3. Dashboard inspector toggle button
+  - Writes paired files per request to `~/.mobygate/captures/`:
+    - `{ts}_{path}_{requestId}.json` — raw inbound body
+    - `{ts}_{path}_{requestId}.summary.txt` — human-readable analysis
+      (system blocks, cache_control markers, message timeline, tool
+      definitions, token breakdown)
+  - On response: appends actual usage from the SDK including
+    `cache_read_input_tokens`, `cache_creation_input_tokens`,
+    `input_tokens`, `output_tokens`, plus computed cache hit % and
+    "savings vs uncached" estimate.
+  - Auto-rotation: keeps last `MOBY_CAPTURE_KEEP=100` captures (200
+    files), prunes oldest in the background.
+
+- **Session inspector UI** at `/inspector`. New focused dashboard for
+  browsing captures:
+  - List view: all recent captures sorted newest-first, one-line stats
+    (timestamp, path, model, msgs, tokens, cache hit %), live polling
+    every 3s.
+  - Detail view: full request body decoded — system blocks (with
+    cache_control highlighted in green), messages timeline (color-coded
+    by role, tool_use/tool_result expanded with previews), tool
+    definitions, response usage stats.
+  - Capture toggle in header — flips the touch file live without
+    restarting mobygate.
+  - Linked from the main dashboard's endpoints row.
+
+- **`mobygate tail` CLI** — `tail -f` style live view of captures as
+  they land. Shows last 10 historical entries, then watches the
+  captures dir for new files. Color-codes `/v1/messages` (green,
+  native shape) vs `/v1/chat/completions` (yellow, OpenAI shape) so
+  shape mismatches jump off the screen.
+
+- **`extractSdkUsage()` helper** in `lib/anthropic.js` — defensive
+  extraction of cache + token fields from SDK result messages,
+  handles both flat (`message.input_tokens`) and nested
+  (`message.usage.input_tokens`) shapes from the Claude Agent SDK.
+  Used by all 4 mobygate handlers (the OpenAI streaming handler also
+  now tracks usage where it didn't before).
+
+- **Connector migration detection** — `openclawConnector.inspect()`
+  now reports "shadow providers": entries in OpenClaw's config that
+  point at mobygate's base URL but aren't registered under our
+  canonical `moby` / `moby-native` names. Catches pre-v0.8.0
+  hand-rolled `claude-max-proxy`-style configs (which silently bypass
+  the native surface). Returned as `shadowProviders: [{ name, api,
+  baseUrl, recommendation }]` in inspect output.
+
+- **Cache endpoints for the dashboard:**
+  - `GET /dashboard/captures` — list captures with summary stats
+  - `GET /dashboard/captures/:filename` — full body + summary for one
+    capture
+  - `GET /dashboard/captures-state` — current toggle state
+  - `POST /dashboard/captures-toggle` — flip toggle live
+  - All require local-origin (DNS-rebinding protection).
+
+### Fixed
+
+- **Connector idempotency** (v0.8.0 OPEN bug). `mobygate connect <id>`
+  run twice with no real change was producing spurious "(changed)"
+  diffs and rewriting byte-identical files. Root cause: `diffSummary`
+  walks objects structurally (sensitive to key order); the actual
+  serialized JSON output was identical. Fix: `writeConfigSafe` now
+  byte-compares the rendered output against the existing file content
+  before deciding to write. Returns `unchanged: true` if no real
+  change. Both `hermesConnector.apply()` and
+  `openclawConnector.apply()` updated to surface this flag.
+
+- **Tool name display in capture analyzer**. OpenAI-shape tools nest
+  the name under `tool.function.name`; the analyzer was only checking
+  `tool.name` and showing `(unnamed)` for everything. Now handles
+  both shapes via the new `toolName(t)` helper.
+
+### Notes
+
+The capture system was the lever that made the entire OpenClaw
+debugging session productive. Without it we had no visibility into
+which wire format clients were using, whether `cache_control` markers
+were being set, where in the request the breakpoints landed, or how
+the conversation was growing turn-over-turn. With it, the diagnosis
+took 60 seconds: "this is `/v1/chat/completions`, no `system` array,
+no cache markers, 33k tokens per turn."
+
+The migration detection in `openclawConnector.inspect()` is a small
+prevent-the-next-occurrence add. If `inspect()` had reported
+`claude-max-proxy` as a shadow provider with a "flip api to
+anthropic-messages" recommendation, today's hour-long forensics would
+have been a single CLI command.
+
 ## [0.8.0] — 2026-04-25
 
 Auto-wire third-party clients to use mobygate. The "find your client's

package/bin/mobygate.js

@@ -480,6 +480,78 @@ function cmdLogs() {
   spawnSync(cmd, args, { stdio: 'inherit' });
 }
 
+// `mobygate tail` — watch captures live, print a one-line summary as
+// each new request lands. Reads the .summary.txt file paired with each
+// new .json file in ~/.mobygate/captures/.
+async function cmdTail() {
+  const { homedir } = await import('os');
+  const { watch, existsSync, readFileSync, mkdirSync, statSync } = await import('fs');
+  const { readdir } = await import('fs/promises');
+  const { join } = await import('path');
+
+  const dir = process.env.MOBYGATE_CAPTURE_DIR
+    || join(process.env.MOBYGATE_HOME || join(homedir(), '.mobygate'), 'captures');
+
+  if (!existsSync(dir)) {
+    print(`Captures directory does not exist yet: ${dir}`);
+    print(`Enable capture (touch ~/.mobygate/.capture-enabled OR set MOBY_CAPTURE=1) and send a request.`);
+    return;
+  }
+
+  // Print recent history first (last 10), then watch.
+  const initial = (await readdir(dir))
+    .filter(n => n.endsWith('.summary.txt'))
+    .map(n => ({ name: n, mtime: statSync(join(dir, n)).mtimeMs }))
+    .sort((a, b) => a.mtime - b.mtime)
+    .slice(-10);
+
+  for (const { name } of initial) {
+    printSummaryLine(join(dir, name));
+  }
+
+  print(''); // blank line separator before live tail
+  print('--- watching for new captures (Ctrl-C to stop) ---');
+
+  const seen = new Set(initial.map(x => x.name));
+  watch(dir, (_event, name) => {
+    if (!name || !name.endsWith('.summary.txt')) return;
+    if (seen.has(name)) return;
+    seen.add(name);
+    // Wait briefly so the file is flushed (fs.watch can fire on the
+    // creation rename before content is fully written).
+    setTimeout(() => printSummaryLine(join(dir, name)), 50);
+  });
+}
+
+function printSummaryLine(summaryPath) {
+  try {
+    const text = readFileSync(summaryPath, 'utf8');
+    const grab = (re) => { const m = text.match(re); return m ? m[1].trim() : '?'; };
+    const ts = grab(/timestamp:\s+(\S+)/).slice(11, 19);
+    const path = grab(/^path:\s+(\S+)/m);
+    const model = grab(/^model:\s+(\S+)/m);
+    const msgs = grab(/^messages:\s+(\d+)/m);
+    const tokens = grab(/grand total:\s+(\d+)/);
+    const hit = grab(/cache hit rate:\s+([\d.]+)%/);
+    const status = grab(/^status:\s+(\S+)/m);
+    const dur = grab(/^duration:\s+(\d+) ms/m);
+
+    const hitDisplay = hit === '?' ? '─' : `${hit}% hit`;
+    const statusDisplay = status === '?' ? '(in flight)' : `${status} ${dur}ms`;
+
+    // Color-code the path: green for /v1/messages (native), yellow for /v1/chat/completions
+    const isNative = path === '/v1/messages';
+    const pathColored = isNative ? `\x1b[32m${path}\x1b[0m` : `\x1b[33m${path}\x1b[0m`;
+    const hitColored = hit === '?' ? hitDisplay
+      : parseFloat(hit) > 50 ? `\x1b[32m${hitDisplay}\x1b[0m`
+      : `\x1b[33m${hitDisplay}\x1b[0m`;
+
+    print(`${ts} ${pathColored.padEnd(35)} ${model.padEnd(22)} msgs=${msgs.padEnd(4)} tok=${tokens.padEnd(6)} ${hitColored.padEnd(20)} ${statusDisplay}`);
+  } catch (e) {
+    print(`(failed to read ${summaryPath}: ${e.message})`);
+  }
+}
+
 async function cmdAuth() {
   section('mobygate auth');
   const status = await getAuthStatus();
@@ -869,6 +941,7 @@ Usage:
   mobygate restart     Stop + start
   mobygate status      Show service + auth + /health state
   mobygate logs        Tail the server log
+  mobygate tail        Watch captures live (request/response inspector)
   mobygate auth        Show auth status + run a refresh probe
   mobygate connect     Auto-wire detected clients (Hermes, OpenClaw) to
                        use mobygate. Add: <id> for one client, --all for
@@ -900,6 +973,7 @@ const COMMANDS = {
   restart: cmdRestart,
   status: cmdStatus,
   logs: cmdLogs,
+  tail: cmdTail,
   auth: cmdAuth,
   uninstall: cmdUninstall,
   version: cmdVersion,

package/index.html

@@ -361,6 +361,7 @@
         <a href="/auth/status?quick=1" class="py-[3px] px-2.5 border border-[#2A2A1F] text-[#C9D9A8] text-[11px] leading-[14px] hover:border-[#5A5F54]">/auth/status</a>
         <a href="/v1/models" class="py-[3px] px-2.5 border border-[#2A2A1F] text-[#C9D9A8] text-[11px] leading-[14px] hover:border-[#5A5F54]">/v1/models</a>
         <a href="/events" class="py-[3px] px-2.5 border border-[#2A2A1F] text-[#C9D9A8] text-[11px] leading-[14px] hover:border-[#5A5F54]">/events</a>
+        <a href="/inspector" class="py-[3px] px-2.5 border border-[#B7E56D] text-[#B7E56D] text-[11px] leading-[14px] hover:bg-[#1A1F12]">/inspector</a>
       </div>
       <div class="flex items-center gap-3">
         <span class="uppercase text-[#5A5F54] text-[10px] leading-3 tracking-[0.12em]" id="f-stream">stream · connecting</span>