mobygate 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,128 @@ 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.6.0] — 2026-04-24
+
+Big one. Native tool calling + in-dashboard self-update.
+
+### Added
+
+- **Native MCP tool calling.** Client-supplied OpenAI tools are now
+  registered with the Claude Agent SDK as in-process MCP tools (with
+  Zod schemas converted from JSON Schema). The model emits genuine
+  `tool_use` content blocks instead of the old `<tool_call>...`
+  text-pattern hack. Tool IDs returned to clients are now Anthropic-
+  native `toolu_*` strings, not synthesized `call_*` ones. New module:
+  `lib/tool-bridge.js`.
+- **Dashboard update banner.** When npm has a newer mobygate, the
+  dashboard shows an orange pill at the top: `v0.6.0 → v0.6.1 available
+  · npm install · [changelog] [dismiss] [update now]`. Clicking
+  "update now" fires `npm install -g mobygate@latest` (or `git pull`
+  for git-mode installs) in a detached child process, restarts the
+  service, and auto-reloads the page. Dismissals stick per-version
+  via localStorage. New module: `lib/updater.js`.
+- New endpoints: `GET /update/check`, `POST /update/apply`,
+  `GET /update/status`. The check endpoint caches the npm registry
+  lookup for 15 minutes so dashboards open all day don't hammer it.
+
+### Changed
+
+- **No more prompt-injected tool definitions.** The `<system>...</system>`
+  block listing available tools as XML is gone — the SDK's MCP
+  registration is the model's source of truth now. This shrinks every
+  tool-enabled prompt by ~200-500 tokens depending on tool count.
+- **Tool-flow detection** moved from text-pattern matching
+  (`hasCompleteToolCall`, `parseToolCalls` regexes) to native
+  `tool_use` content-block detection in the assistant message stream
+  (`hasToolUse`, `extractToolUses`). The moment a tool_use lands,
+  we abort the SDK and emit OpenAI-shape `tool_calls`.
+- **`alwaysLoad: true`** on every registered tool. Without this, the
+  SDK lazily defers MCP tool schemas — the model has to call the
+  built-in `ToolSearch` tool to fetch each definition before invoking,
+  which leaks through to OpenAI clients as a confusing tool_call
+  for `ToolSearch` instead of their actual tool. Eager loading
+  keeps the surface clean.
+
+### Removed
+
+- `buildToolInstructions` — the `<tool_call>...` protocol prose.
+- `parseToolCalls` — the regex parser for `<tool_call>` JSON blocks.
+- `hasCompleteToolCall` — the streaming-buffer heuristic that aborted
+  the SDK when a complete tag pair appeared.
+- `formatAssistantForReplay`'s tool_calls→`<tool_call>` text
+  serialization (assistant replay is now best-effort text only).
+- The "Use the tool results above to continue toward the final answer"
+  nudge — tool results are visible in conversation context now, so
+  the model handles continuation naturally without coaxing.
+
+### Known limitation (Phase 1 deliberate)
+
+- Tool *results* coming back from the client are still spliced as
+  `<tool_results>` text in the resumed prompt, not native Anthropic
+  `tool_result` content blocks. Reason: aborting the SDK on a
+  `tool_use` block prevents the assistant turn from being persisted
+  in session state — on resume, native tool_result blocks have
+  nothing to bind to and the model re-calls the tool. Text-form
+  results work because the resumed model has the prior turn in
+  context. Phase 2's full Anthropic Messages wire surface will
+  keep the SDK alive through the tool turn and switch to native
+  tool_result blocks end-to-end.
+
+### Migration
+
+- No client-facing changes. Existing OpenAI-shape requests with
+  `tools: [...]` work the same as before — what's improved is
+  reliability ("Model returned empty after tool calls" warnings
+  should largely disappear) and surface fidelity (tool_call IDs
+  are now native Anthropic IDs, not synthesized).
+- Update with `mobygate update` (CLI) or click the new "update now"
+  button in the dashboard once it appears.
+
+## [0.5.3] — 2026-04-19
+
+Security pass.
+
+### Changed
+
+- **Default listen address is now `127.0.0.1`** (loopback only). Earlier
+  versions called `app.listen(PORT)` with no host, which on macOS binds
+  to `::` (IPv6 all interfaces) — meaning anyone on your Wi-Fi could
+  reach `:3456`, use your Claude Max subscription, and read your
+  request logs. New default blocks that; startup banner now calls
+  out the bind ("loopback only" vs "⚠ network-reachable — add auth").
+- **Opt-in LAN sharing** via `bind: 0.0.0.0` (or any specific
+  interface) in `~/.mobygate/config.yaml`, or via the `BIND` env
+  var. If you opt in, consider putting an auth proxy in front of
+  the port — the dashboard and HTTP endpoints have no authentication.
+
+### Fixed
+
+- **Dashboard XSS** in live-requests and sessions rows. User-
+  controlled fields (`model`, `session key`, `model` on session
+  entries) were being interpolated directly into `innerHTML`. A
+  malicious local process that can reach :3456 could have
+  injected `<script>` via a crafted `model` string and executed
+  JS in whichever browser tab had the dashboard open. Added an
+  `escHtml()` helper and wrapped every user-controlled field
+  interpolated via innerHTML.
+- Added `hono >= 4.12.14` as an npm `overrides` entry to clear
+  the single `moderate` audit finding (a transitive via
+  `@modelcontextprotocol/sdk` → `hono/jsx`). We don't actually
+  load hono/jsx, so it was never exploitable, but `npm audit`
+  now reports `0 vulnerabilities` — cleaner for downstream users.
+
+### Migration
+
+For existing installs: `mobygate update` or
+`npm install -g mobygate@latest` — the postinstall hook restarts
+your service and the new loopback-only bind kicks in.
+
+If you were **intentionally** exposing mobygate on the LAN (e.g.,
+"one proxy for the family"), add `bind: 0.0.0.0` to
+`~/.mobygate/config.yaml` and restart. Strongly recommend adding
+an auth proxy (nginx with Basic Auth, Cloudflare Access, etc.)
+in front of the port if you do this.
+
 ## [0.5.2] — 2026-04-19
 
 ### Added

package/index.html

@@ -49,6 +49,34 @@
 <body class="antialiased">
   <div class="mx-auto px-12 pt-8 pb-7 flex flex-col gap-6 max-w-[1440px] min-h-screen">
 
+    <!-- ===== Update banner ===== -->
+    <!-- Hidden until /update/check reports updateAvailable=true. During
+         apply, this becomes a progress strip showing live log tail. -->
+    <section id="updateBanner" style="display:none" class="items-center gap-4 py-3 px-5 bg-[#121210] border-l-2 border-l-[#E89B2E] border-t border-b border-r border-[#2A2A1F] rounded-r-md">
+      <div class="flex items-center gap-2.5">
+        <span class="rounded-full bg-[#E89B2E] w-2 h-2 pulse-dot"></span>
+        <span class="uppercase text-[#E89B2E] font-medium text-[10px] tracking-[0.22em]">Update</span>
+      </div>
+      <div id="updateBannerText" class="grow text-[#F3EFE4] text-xs leading-4"></div>
+      <div id="updateBannerActions" class="flex items-center gap-2 shrink-0">
+        <a id="updateBannerChangelog" href="https://github.com/khnfrhn/mobygate/blob/master/CHANGELOG.md" target="_blank" rel="noreferrer" class="text-[#8A9A6A] hover:text-[#C9D9A8] text-[11px] tracking-[0.04em] underline decoration-dotted">changelog</a>
+        <button id="updateDismissBtn" class="rounded-full py-1.5 px-3 border border-[#2A2A1F] text-[#8A9A6A] hover:text-[#C9D9A8] hover:border-[#5A5F54] font-medium text-[11px] tracking-[0.04em] transition">dismiss</button>
+        <button id="updateApplyBtn" class="rounded-full py-1.5 px-3.5 bg-[#E89B2E] hover:brightness-110 text-[#0B0B09] font-bold text-[11px] tracking-[0.04em] transition">update now</button>
+      </div>
+    </section>
+    <!-- Apply-in-progress shelf: expands below the banner during update. -->
+    <section id="updateProgress" style="display:none" class="flex-col gap-2 py-3 px-5 bg-[#121210] border border-[#2A2A1F] rounded-md">
+      <div class="flex items-center justify-between">
+        <div class="flex items-center gap-2">
+          <span id="updateSpinner" class="rounded-full bg-[#E89B2E] w-2 h-2 pulse-dot"></span>
+          <span id="updateProgressTitle" class="uppercase text-[#C9D9A8] font-medium text-[10px] tracking-[0.22em]">Installing</span>
+          <span id="updateProgressSub" class="text-[#5A5F54] text-[11px]"></span>
+        </div>
+        <button id="updateProgressClose" style="display:none" class="text-[#5A5F54] hover:text-[#C9D9A8] text-[11px]">close ✕</button>
+      </div>
+      <pre id="updateProgressLog" class="text-[11px] leading-[15px] text-[#8A9A6A] max-h-[180px] overflow-auto whitespace-pre-wrap m-0"></pre>
+    </section>
+
     <!-- ===== Header ===== -->
     <header class="flex justify-between items-center shrink-0">
       <div class="flex items-center gap-[22px]">
@@ -357,6 +385,17 @@
   <script type="module">
     // ───────────────────────── helpers
     const $ = (id) => document.getElementById(id);
+    // Escape HTML in user-controlled strings (request model/session/error
+    // fields, session keys, etc.) before innerHTML interpolation. The
+    // dashboard is unauthenticated, so any process that can reach the
+    // proxy could otherwise inject a <script> via a crafted request and
+    // execute JS in whoever's tab is viewing the dashboard.
+    const escHtml = (s) => String(s ?? '')
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
     const fmt = {
       time(ts) { return new Date(ts).toLocaleTimeString([], { hour12: false }); },
       ms(n)    { return n == null ? '—' : `${n}`; },
@@ -553,10 +592,10 @@
         <div class="w-[72px] shrink-0 text-[#C9D9A8] text-xs leading-4">${fmt.time(startEv.ts)}</div>
         <div class="w-[100px] flex shrink-0 gap-1">${kindChips(startEv)}</div>
         <div class="w-[180px] flex flex-col shrink-0 gap-0.5">
-          <div class="text-[#F3EFE4] text-xs leading-4 truncate">${startEv.model || '—'}</div>
-          <div class="text-[#5A5F54] text-[10px] leading-3">${fmt.modelBase(startEv.model)} · ${fmt.modelCtx(startEv.resolvedModel)}</div>
+          <div class="text-[#F3EFE4] text-xs leading-4 truncate">${escHtml(startEv.model) || '—'}</div>
+          <div class="text-[#5A5F54] text-[10px] leading-3">${escHtml(fmt.modelBase(startEv.model))} · ${escHtml(fmt.modelCtx(startEv.resolvedModel))}</div>
         </div>
-        <div class="w-[110px] shrink-0 text-[#8A9A6A] text-xs leading-4 truncate" title="${startEv.session || ''}">${startEv.session ? fmt.short(startEv.session) : '—'}</div>
+        <div class="w-[110px] shrink-0 text-[#8A9A6A] text-xs leading-4 truncate" title="${escHtml(startEv.session || '')}">${startEv.session ? escHtml(fmt.short(startEv.session)) : '—'}</div>
         <div class="grow flex flex-col gap-1">${latencyBar(endEv)}</div>
         <div class="w-[100px] text-right shrink-0 text-[#8A9A6A] text-[11px] leading-[14px]">${endEv && (endEv.inputTokens || endEv.outputTokens) ? `${endEv.inputTokens || 0}/${endEv.outputTokens || 0}` : '—'}</div>
         <div class="w-[70px] flex justify-end shrink-0">${statusPill(endEv)}</div>
@@ -680,12 +719,12 @@
           const row = document.createElement('div');
           row.className = 'flex items-center py-3 px-6 gap-4 border-b border-[#1A1A15]';
           row.innerHTML = `
-            <div class="grow min-w-0 text-[#F3EFE4] text-xs leading-4 truncate" title="${s.key}">${s.key}</div>
-            <div class="w-[160px] shrink-0 text-[#8A9A6A] text-xs leading-4 truncate">${s.model || '—'}</div>
-            <div class="w-[60px] text-right shrink-0 text-[#8A9A6A] text-xs">${s.messageCount}</div>
+            <div class="grow min-w-0 text-[#F3EFE4] text-xs leading-4 truncate" title="${escHtml(s.key)}">${escHtml(s.key)}</div>
+            <div class="w-[160px] shrink-0 text-[#8A9A6A] text-xs leading-4 truncate">${escHtml(s.model) || '—'}</div>
+            <div class="w-[60px] text-right shrink-0 text-[#8A9A6A] text-xs">${Number(s.messageCount) || 0}</div>
             <div class="w-[80px] text-right shrink-0 text-[#5A5F54] text-[11px]">${fmt.uptime(s.idleSec)}</div>
             <div class="w-[80px] text-right shrink-0 text-[#5A5F54] text-[11px]">${fmt.uptime(s.ttlRemainingSec)} left</div>
-            <button class="text-[#E89B2E] text-[11px] hover:brightness-110 shrink-0" data-key="${s.key}">expire</button>
+            <button class="text-[#E89B2E] text-[11px] hover:brightness-110 shrink-0" data-key="${escHtml(s.key)}">expire</button>
           `;
           row.querySelector('button').addEventListener('click', async () => {
             await fetch('/sessions/' + encodeURIComponent(s.key), { method: 'DELETE' });
@@ -793,6 +832,117 @@
       }
     }, 1000);
 
+    // ───────────────────────── Updater
+    // Dashboard-driven upgrade flow. On load (and every 30 min) we ask
+    // /update/check whether a newer mobygate is on npm. If so, a pill
+    // appears at the top of the page — click "update now" to fire the
+    // update, watch log lines stream in, then auto-reload when the new
+    // server is up. The child process is detached, so the server
+    // restart doesn't orphan it.
+    const UPDATE_DISMISS_KEY = 'mobygate:update:dismissedVersion';
+    let updateInfo = null;
+    let updatePollTimer = null;
+
+    function showBanner(info) {
+      if (!info?.updateAvailable) {
+        $('updateBanner').style.display = 'none';
+        return;
+      }
+      // Respect dismissal: if the user dismissed this exact version, don't
+      // re-pester until a newer one lands.
+      const dismissed = localStorage.getItem(UPDATE_DISMISS_KEY);
+      if (dismissed === info.latest) {
+        $('updateBanner').style.display = 'none';
+        return;
+      }
+      const msg = info.canApply
+        ? `v${escHtml(info.current)} → <span class="text-[#B7E56D]">v${escHtml(info.latest)}</span> available · <span class="text-[#5A5F54]">${escHtml(info.installMode)} install</span>`
+        : `v${escHtml(info.current)} → <span class="text-[#B7E56D]">v${escHtml(info.latest)}</span> available · <span class="text-[#E89B2E]">${escHtml(info.installMode)} install — update manually</span>`;
+      $('updateBannerText').innerHTML = msg;
+      $('updateApplyBtn').style.display = info.canApply ? '' : 'none';
+      $('updateBanner').style.display = 'flex';
+    }
+
+    async function checkForUpdates({ force = false } = {}) {
+      try {
+        const r = await fetch(`/update/check${force ? '?force=1' : ''}`);
+        if (!r.ok) return;
+        updateInfo = await r.json();
+        showBanner(updateInfo);
+      } catch (e) { /* offline is fine */ }
+    }
+
+    function renderUpdateLog(lines) {
+      const el = $('updateProgressLog');
+      el.textContent = (lines || []).join('\n');
+      // Pin to bottom so the user sees the latest line.
+      el.scrollTop = el.scrollHeight;
+    }
+
+    async function pollUpdateStatus() {
+      try {
+        const r = await fetch('/update/status?lines=200');
+        if (!r.ok) return;
+        const s = await r.json();
+        renderUpdateLog(s.lines);
+        if (!s.running) {
+          // Update finished. The service restart may have already swapped
+          // the running binary — our `currentVersion` reflects whatever
+          // server answered. If it matches `latest`, celebrate. Either
+          // way, give it a moment then reload so the dashboard comes
+          // back on the new code path.
+          clearInterval(updatePollTimer); updatePollTimer = null;
+          $('updateSpinner').classList.remove('pulse-dot');
+          $('updateSpinner').classList.remove('bg-[#E89B2E]');
+          $('updateSpinner').classList.add('bg-[#B7E56D]');
+          $('updateProgressTitle').textContent = 'Installed';
+          $('updateProgressSub').textContent = `now on v${s.currentVersion} — reloading in 3s…`;
+          $('updateProgressClose').style.display = '';
+          setTimeout(() => location.reload(), 3000);
+        }
+      } catch (e) {
+        // Server is mid-restart — keep polling, it'll come back.
+      }
+    }
+
+    function startUpdateProgress(mode) {
+      $('updateBanner').style.display = 'none';
+      $('updateProgress').style.display = 'flex';
+      $('updateProgressSub').textContent = mode ? `(${mode} install)` : '';
+      $('updateProgressTitle').textContent = 'Installing';
+      $('updateSpinner').classList.add('pulse-dot');
+      $('updateProgressLog').textContent = 'starting update…';
+      if (updatePollTimer) clearInterval(updatePollTimer);
+      updatePollTimer = setInterval(pollUpdateStatus, 1500);
+      pollUpdateStatus();
+    }
+
+    $('updateApplyBtn')?.addEventListener('click', async () => {
+      $('updateApplyBtn').disabled = true;
+      try {
+        const r = await fetch('/update/apply', { method: 'POST' });
+        const j = await r.json().catch(() => ({}));
+        if (!r.ok || !j.started) {
+          $('updateBannerText').innerHTML += ` <span class="text-[#E89B2E]">— ${escHtml(j.error || 'update failed to start')}</span>`;
+          $('updateApplyBtn').disabled = false;
+          return;
+        }
+        startUpdateProgress(j.mode);
+      } catch (e) {
+        $('updateBannerText').innerHTML += ` <span class="text-[#E89B2E]">— ${escHtml(e.message)}</span>`;
+        $('updateApplyBtn').disabled = false;
+      }
+    });
+
+    $('updateDismissBtn')?.addEventListener('click', () => {
+      if (updateInfo?.latest) localStorage.setItem(UPDATE_DISMISS_KEY, updateInfo.latest);
+      $('updateBanner').style.display = 'none';
+    });
+
+    $('updateProgressClose')?.addEventListener('click', () => {
+      $('updateProgress').style.display = 'none';
+    });
+
     // Kick off
     loadSnapshot();
     loadAuth({ verify: false });
@@ -800,6 +950,21 @@
     loadLogs();
     armLogAutoRefresh();
     connectStream();
+    // Surface update availability on load + every 30 min. The backend
+    // caches the npm registry lookup for 15 min, so this doesn't hammer
+    // the registry even with the dashboard open all day.
+    checkForUpdates();
+    setInterval(() => checkForUpdates(), 30 * 60 * 1000);
+    // If an update is in-flight when the page loads (e.g., user refreshed
+    // mid-apply), pick up where it left off.
+    (async () => {
+      try {
+        const r = await fetch('/update/status?lines=50');
+        if (!r.ok) return;
+        const s = await r.json();
+        if (s.running) startUpdateProgress(s.mode);
+      } catch {}
+    })();
   </script>
 </body>
 </html>

package/lib/config.js

@@ -27,6 +27,7 @@ export const LOGS_DIR = join(CONFIG_DIR, 'logs');
 
 const DEFAULTS = {
   port: 3456,
+  bind: '127.0.0.1',          // loopback only by default (no LAN exposure)
   default_model: 'claude-opus-4-7[1m]',
   session_ttl_minutes: 60,
   max_concurrent: null,       // reserved for future (per-session throttling)
@@ -57,6 +58,7 @@ export function loadConfig() {
 
   const merged = {
     port: parseInt(process.env.PORT || String(fileConfig.port ?? DEFAULTS.port), 10),
+    bind: process.env.BIND || fileConfig.bind || DEFAULTS.bind,
     default_model: process.env.DEFAULT_MODEL || fileConfig.default_model || DEFAULTS.default_model,
     session_ttl_minutes: parseInt(
       process.env.SESSION_TTL_MINUTES
@@ -91,6 +93,13 @@ export function writeConfig(values = {}) {
     `# HTTP port the proxy listens on.`,
     `port: ${merged.port}`,
     '',
+    `# Network interface to bind to. Defaults to 127.0.0.1 (loopback only —`,
+    `# the proxy is only reachable from this machine). Change to 0.0.0.0 to`,
+    `# share it on the LAN (e.g., "one proxy for the whole family"), but be`,
+    `# aware: whoever can reach :port can use your Claude Max subscription`,
+    `# and read logs containing your prompts. Add auth if you go LAN-public.`,
+    `bind: ${JSON.stringify(merged.bind)}`,
+    '',
     `# Default Claude model when the client does not specify one.`,
     `# Other aliases (opus, sonnet, haiku) resolve per MODEL_MAP in server.js.`,
     `default_model: ${JSON.stringify(merged.default_model)}`,

package/lib/tool-bridge.js

@@ -0,0 +1,257 @@
+/**
+ * Native tool bridge — translates between OpenAI client tools and the
+ * Claude Agent SDK's MCP-tool model.
+ *
+ * Why this exists (Phase 1 of the mobygate native-tools refactor):
+ *
+ * Until now, mobygate handled client-supplied tools by injecting their
+ * schemas into the system prompt as <tool> XML and instructing the model
+ * to emit <tool_call>{...}</tool_call> tags in its text output. We then
+ * regex-parsed those tags. Fragile in obvious ways: the model sometimes
+ * wrapped tags in code fences, sometimes hallucinated partial blocks,
+ * and the "empty after tool_results" nudge existed to paper over the
+ * model treating bare <tool_results> as inert data.
+ *
+ * The SDK actually supports native tool definitions via MCP — but its
+ * MCP model assumes the **handler runs in-process** and returns a
+ * synchronous result. Our case is different: we're a proxy. The actual
+ * tool implementations live on the *other* side of an HTTP boundary,
+ * inside the client (Hermes / OpenClaw / etc.). We can't run them.
+ *
+ * The trick: register client tools as MCP tools with stub handlers that
+ * never resolve. The model emits **native** `tool_use` content blocks
+ * (in the SDKAssistantMessage stream, not buried in text). We watch the
+ * stream, abort the SDK on the first complete `tool_use`, and surface
+ * it to the client as an OpenAI `tool_calls` response. The stub handler
+ * is then aborted via the SDK's signal — we never actually execute it,
+ * the client does.
+ *
+ * The other end of the round-trip: when the client sends a follow-up
+ * request with tool results (role:'tool' messages), we convert those
+ * into native `tool_result` content blocks inside an SDKUserMessage,
+ * resuming the SDK session. The model sees structured tool results,
+ * not <tool_result> XML, and continues the conversation cleanly.
+ *
+ * Names round-trip via the MCP prefix convention. A client tool named
+ * `getWeather` is registered as `mcp__mobygate__getWeather` with the
+ * SDK; the model emits tool_use blocks under that prefixed name; we
+ * strip the prefix on the way back so the client sees its original name.
+ */
+
+import { z } from 'zod';
+import { tool, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
+
+export const MCP_SERVER_NAME = 'mobygate';
+export const MCP_TOOL_PREFIX = `mcp__${MCP_SERVER_NAME}__`;
+
+// ---------------------------------------------------------------------------
+// JSON Schema → Zod RawShape
+// ---------------------------------------------------------------------------
+// The SDK's `tool()` helper takes a Zod RawShape (a record of ZodTypes,
+// like `{name: z.string(), age: z.number()}`) — NOT a JSON Schema object.
+// OpenAI clients send JSON Schema (`{type:'object', properties:{...}, required:[...]}`),
+// so we need to convert. This handles the common cases that cover ~95% of
+// real-world tool schemas; anything weirder falls through to z.unknown().
+
+function jsonSchemaPropToZod(prop) {
+  if (!prop || typeof prop !== 'object') return z.unknown();
+
+  // Handle enums up front — they apply across types.
+  if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+    const stringy = prop.enum.every((v) => typeof v === 'string');
+    if (stringy) return z.enum(prop.enum);
+    // mixed-type enums fall through to z.union of literals
+    return z.union(prop.enum.map((v) => z.literal(v)));
+  }
+
+  switch (prop.type) {
+    case 'string':  return z.string();
+    case 'number':  return z.number();
+    case 'integer': return z.number().int();
+    case 'boolean': return z.boolean();
+    case 'null':    return z.null();
+    case 'array': {
+      const item = prop.items ? jsonSchemaPropToZod(prop.items) : z.unknown();
+      return z.array(item);
+    }
+    case 'object': {
+      const shape = jsonSchemaToZodShape(prop);
+      return z.object(shape).passthrough();
+    }
+    default: return z.unknown();
+  }
+}
+
+/**
+ * Convert a JSON Schema *object* (with `properties` + `required`) into
+ * a Zod RawShape suitable for the SDK's `tool()` helper.
+ *
+ * Returns an empty shape `{}` when the schema isn't an object — the
+ * caller will pass this to `tool()`, and the model will see "no
+ * structured input expected." That's the right default for tool defs
+ * that arrive without a properties block (which OpenAI permits).
+ */
+export function jsonSchemaToZodShape(schema) {
+  if (!schema || schema.type !== 'object' || !schema.properties) return {};
+  const shape = {};
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    let zType = jsonSchemaPropToZod(prop);
+    if (!required.has(key)) zType = zType.optional();
+    if (prop?.description) zType = zType.describe(prop.description);
+    shape[key] = zType;
+  }
+  return shape;
+}
+
+// ---------------------------------------------------------------------------
+// Build the MCP server that exposes client tools to the SDK
+// ---------------------------------------------------------------------------
+
+/**
+ * Stub handler. The model emits a tool_use block, the SDK calls us, but
+ * we don't actually have an implementation to run — the client does.
+ * So we wait. The stream-watcher in server.js will abort the SDK as
+ * soon as it sees the tool_use block, which propagates here as a signal
+ * abort. We reject and the SDK cleans up.
+ *
+ * The 30s safety timeout is for the (rare) case where the SDK fires our
+ * handler but the abort never propagates back — we don't want to leak
+ * a Promise forever. 30s is well past any reasonable abort latency.
+ */
+function deferredToolHandler(_args, extra) {
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      cleanup();
+      reject(new Error('mobygate: tool execution deferred to client (aborted)'));
+    };
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error('mobygate: tool execution deferred to client (timeout)'));
+    }, 30_000);
+    function cleanup() {
+      clearTimeout(timer);
+      extra?.signal?.removeEventListener?.('abort', onAbort);
+    }
+    if (extra?.signal?.aborted) return onAbort();
+    extra?.signal?.addEventListener?.('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * Build an in-process MCP server exposing the client's tools to the SDK.
+ * Returns the McpSdkServerConfigWithInstance; pass it to `query({options: { mcpServers: { [MCP_SERVER_NAME]: config } }})`.
+ *
+ * Returns `null` when there are no valid tools — caller should skip
+ * MCP setup entirely in that case.
+ */
+export function buildClientToolsServer(openaiTools) {
+  if (!Array.isArray(openaiTools) || openaiTools.length === 0) return null;
+
+  const toolDefs = [];
+  for (const t of openaiTools) {
+    if (t?.type !== 'function' || !t.function?.name) continue;
+    const fn = t.function;
+    const shape = jsonSchemaToZodShape(fn.parameters);
+    toolDefs.push(tool(
+      fn.name,
+      fn.description || `Client-defined tool: ${fn.name}`,
+      shape,
+      deferredToolHandler,
+      // alwaysLoad: the SDK otherwise marks MCP tools as "deferred" — the
+      // model has to call the built-in `ToolSearch` to fetch the schema
+      // before invoking. That round-trip is invisible to OpenAI clients,
+      // who see a confusing tool_call for ToolSearch instead of getWeather.
+      // Eagerly loading our tools keeps the OpenAI surface clean.
+      { alwaysLoad: true },
+    ));
+  }
+  if (toolDefs.length === 0) return null;
+
+  return createSdkMcpServer({
+    name: MCP_SERVER_NAME,
+    version: '1.0.0',
+    tools: toolDefs,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tool-use extraction (SDK assistant message → OpenAI tool_calls)
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk an SDKAssistantMessage's content array for native `tool_use` blocks.
+ * Returns an array of `{ id, name, arguments }` formatted for OpenAI
+ * tool_calls — name has the MCP prefix stripped, arguments is a JSON string.
+ *
+ * Returns `[]` when the message has no tool_use blocks (most assistant
+ * messages don't — they're just text deltas).
+ */
+export function extractToolUses(assistantMessage) {
+  const content = assistantMessage?.message?.content;
+  if (!Array.isArray(content)) return [];
+  const calls = [];
+  for (const block of content) {
+    if (block?.type !== 'tool_use' || !block.id || !block.name) continue;
+    // Strip the MCP prefix so the client sees its original tool name.
+    const name = block.name.startsWith(MCP_TOOL_PREFIX)
+      ? block.name.slice(MCP_TOOL_PREFIX.length)
+      : block.name;
+    let argsString = '{}';
+    try { argsString = JSON.stringify(block.input ?? {}); } catch {}
+    calls.push({ id: block.id, name, arguments: argsString });
+  }
+  return calls;
+}
+
+/**
+ * Quick liveness check used by the stream loop to decide whether to abort
+ * early. Returns true the moment any tool_use block appears.
+ */
+export function hasToolUse(assistantMessage) {
+  const content = assistantMessage?.message?.content;
+  if (!Array.isArray(content)) return false;
+  return content.some((b) => b?.type === 'tool_use');
+}
+
+// ---------------------------------------------------------------------------
+// Tool results (OpenAI tool messages → Anthropic tool_result content blocks)
+// ---------------------------------------------------------------------------
+
+/**
+ * Format OpenAI role:'tool' messages as a single user-readable text
+ * block to splice into a resumed prompt.
+ *
+ * NOTE: Phase 1 deliberately does *not* round-trip tool results as
+ * native Anthropic `tool_result` content blocks. Why: when we abort
+ * the SDK on a tool_use, the assistant turn isn't persisted in the
+ * SDK's session state (we observed `msgs=1` on resume after a tool
+ * call, meaning the partial turn was dropped). On resume, sending a
+ * native tool_result block then has nothing to bind to — the model
+ * sees an orphan tool_result and re-calls the tool.
+ *
+ * Phase 2's full Anthropic Messages wire format will keep the SDK
+ * alive long enough to persist the turn properly. Until then, text-
+ * form tool results (which the model handles fine — it has the
+ * preceding tool_use in resume context) is the pragmatic answer.
+ *
+ * Returns a single string suitable for prepending to (or replacing)
+ * the user's prompt text on a resumed turn. Returns '' when there
+ * are no tool messages.
+ */
+export function toolMessagesToText(toolMessages) {
+  const lines = [];
+  for (const msg of toolMessages) {
+    if (msg?.role !== 'tool') continue;
+    const id = msg.tool_call_id || 'unknown';
+    const name = msg.name || '';
+    const content = typeof msg.content === 'string'
+      ? msg.content
+      : Array.isArray(msg.content)
+        ? msg.content.map((c) => (typeof c === 'string' ? c : c?.text || '')).join('')
+        : (msg.content == null ? '' : String(msg.content));
+    lines.push(`<tool_result id="${id}"${name ? ` name="${name}"` : ''}>\n${content}\n</tool_result>`);
+  }
+  if (lines.length === 0) return '';
+  return `<tool_results>\n${lines.join('\n')}\n</tool_results>`;
+}