mobygate 0.5.3 → 0.6.1

package/CHANGELOG.md

@@ -4,6 +4,94 @@ 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.1] — 2026-04-24
+
+### Fixed
+
+- **`mobygate update` on Windows** failed with `spawnSync npm ENOENT`
+  because `npm` resolves to `npm.cmd` (a batch file) on Windows, and
+  Node's `spawn` won't pick up `.cmd` extensions without going through
+  cmd.exe. Added `shell: IS_WIN` to every npm/git invocation in the
+  CLI's update path. The dashboard's update endpoint already had this
+  fix in v0.6.0; now the CLI matches.
+
+## [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.

package/bin/mobygate.js

@@ -564,8 +564,13 @@ async function cmdUpdate() {
   print(c.dim(`Current: v${pkg.version} · ${mode} install at ${REPO_ROOT}`));
 
   // ---- Look up latest published version on npm
+  // shell: IS_WIN is required on Windows because `npm` is `npm.cmd`
+  // (a batch file), and Node's spawn won't resolve .cmd extensions
+  // without going through cmd.exe. Same for git on Windows where some
+  // distributions install git as a shim. On macOS/Linux these are real
+  // binaries, so the flag is a no-op.
   info('Checking npm for the latest release...');
-  const view = spawnSync('npm', ['view', 'mobygate', 'version'], { encoding: 'utf8', timeout: 10_000 });
+  const view = spawnSync('npm', ['view', 'mobygate', 'version'], { encoding: 'utf8', timeout: 10_000, shell: IS_WIN });
   if (view.status !== 0) {
     return die(`Couldn't reach npm registry: ${view.stderr?.trim() || view.error?.message || 'unknown'}`);
   }
@@ -579,15 +584,15 @@ async function cmdUpdate() {
   // ---- Perform the upgrade
   if (mode === 'npm') {
     info(`Running \`npm install -g mobygate@latest\`...`);
-    const r = spawnSync('npm', ['install', '-g', 'mobygate@latest'], { stdio: 'inherit' });
+    const r = spawnSync('npm', ['install', '-g', 'mobygate@latest'], { stdio: 'inherit', shell: IS_WIN });
     if (r.status !== 0) return die('npm install failed. See output above.');
     ok(`Installed mobygate@${latest}`);
   } else if (mode === 'git') {
     info(`Running \`git pull\` in ${REPO_ROOT}...`);
-    const pull = spawnSync('git', ['-C', REPO_ROOT, 'pull', '--ff-only'], { stdio: 'inherit' });
+    const pull = spawnSync('git', ['-C', REPO_ROOT, 'pull', '--ff-only'], { stdio: 'inherit', shell: IS_WIN });
     if (pull.status !== 0) return die('git pull failed. Resolve conflicts and retry.');
     info(`Running \`npm install\`...`);
-    const install = spawnSync('npm', ['install'], { cwd: REPO_ROOT, stdio: 'inherit' });
+    const install = spawnSync('npm', ['install'], { cwd: REPO_ROOT, stdio: 'inherit', shell: IS_WIN });
     if (install.status !== 0) return die('npm install failed. See output above.');
     ok(`Pulled and installed. See git log for what changed.`);
   } else {

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]">
@@ -804,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 });
@@ -811,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/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>`;
+}