mixdog 0.7.18 → 0.8.0

package/src/gateway/server.mjs

@@ -1,713 +0,0 @@
-/**
- * mixdog — Anthropic-compatible local gateway.
- *
- * A loopback-only HTTP server that speaks the Anthropic Messages API
- * (`POST /v1/messages`) so an external Claude Code can point
- * ANTHROPIC_BASE_URL at it and have its MAIN model routed to ANY mixdog
- * provider via the unified provider registry:
- *
- *     Anthropic /v1/messages request
- *       → toCommon() messages
- *       → getProvider(name).send(messages, model, tools, opts)
- *       → Anthropic JSON (non-stream) OR Anthropic SSE (stream)
- *
- * The SSE sequence (message_start → content_block_start →
- * content_block_delta{text_delta} → content_block_stop → message_delta →
- * message_stop) is the exact shape parseSSEStream() in
- * src/agent/orchestrator/providers/anthropic-oauth.mjs consumes.
- *
- * send() returns { content, toolCalls, stopReason, usage }; onStreamDelta
- * is heartbeat-only (no token text) today, so streaming is a PSEUDO-stream:
- * the full reply is assembled, then chunked back out as SSE. tool_use is
- * fully mapped (request tools → send(); toolCalls → tool_use blocks /
- * input_json_delta SSE). Real token-level streaming is a LATER step.
- *
- * Two ways to run:
- *   1. Imported: `startGatewayServer({ provider, model, port, log })` —
- *      kept as a named export for tests / ad-hoc in-process hosting.
- *   2. Forked directly via `fork('src/gateway/server.mjs')` — config is
- *      read from the agent config + MIXDOG_GATEWAY_* env. The parent kills
- *      this process at shutdown.
- *
- * Module is OFF by default (modules.gateway.enabled !== true) so existing
- * installs are unaffected.
- */
-
-import http from 'http';
-import os from 'os';
-import path from 'path';
-import { pathToFileURL } from 'url';
-import { readSection } from '../shared/config.mjs';
-import { updateJsonAtomicSync } from '../shared/atomic-file.mjs';
-import { isInclusiveProvider } from '../shared/llm/cost.mjs';
-import {
-  buildGatewayLimits,
-  gatewayAdvertFields,
-  gatewaySendOptions,
-  prepareGatewayMessages,
-  readGatewayRouteInfo,
-  recordGatewayUsageEvent,
-  summarizeGatewayUsage,
-} from './route-meta.mjs';
-import {
-  fetchOAuthUsageSnapshot,
-  readCachedOAuthUsageSnapshot,
-} from './oauth-usage.mjs';
-import {
-  CLAUDE_CURRENT_MODE,
-  readClaudeCodeCurrentRoute,
-} from './claude-current.mjs';
-
-// Fixed default port so an external Claude Code's ANTHROPIC_BASE_URL can be
-// a stable URL. Overridable via env (MIXDOG_GATEWAY_PORT) or config
-// (gateway.port). Kept off the ephemeral-port path the status server uses —
-// that server is discovered via an advert file, whereas this one is typed
-// into a client env var. 3468 sits just ABOVE the channels proxy range
-// (PROXY_PORT_MIN=3460 / PROXY_PORT_MAX=3467 in src/channels/index.mjs) and
-// clear of setup's 3458, so the default never collides.
-export const DEFAULT_GATEWAY_PORT = 3468;
-const GATEWAY_HOST = '127.0.0.1';
-
-const RUNTIME_ROOT = process.env.MIXDOG_RUNTIME_ROOT
-  ? path.resolve(process.env.MIXDOG_RUNTIME_ROOT)
-  : path.join(os.tmpdir(), 'mixdog');
-const ACTIVE_INSTANCE_FILE = path.join(RUNTIME_ROOT, 'active-instance.json');
-
-function parsePositivePid(value) {
-  const pid = Number(value);
-  return Number.isFinite(pid) && pid > 0 ? pid : null;
-}
-
-// process.kill(pid, 0) probes existence without delivering a signal: it
-// throws ESRCH for a dead pid and EPERM for a live one we can't signal
-// (so EPERM counts as alive). Mirrors _isPidAliveLocal in src/memory/index.mjs.
-function isPidAlive(pid) {
-  const n = parsePositivePid(pid);
-  if (!n) return false;
-  try { process.kill(n, 0); return true; }
-  catch (err) { return err && err.code === 'EPERM'; }
-}
-
-const GATEWAY_SERVER_PID = parsePositivePid(process.pid);
-
-// ── Config ───────────────────────────────────────────────────────────
-// Mirrors how src/agent/orchestrator/config.mjs reads provider config:
-// read a top-level section from mixdog-config.json (readSection returns {}
-// when absent / malformed) and overlay env. Every field is optional and
-// resolves to a safe, disabled-friendly default so an enabled-but-unconfigured
-// module is a no-op (refuses to route) rather than a crash.
-//
-//   gateway.defaultProvider  → routing target provider name (registry key)
-//   gateway.defaultModel     → model id passed to provider.send()
-//   gateway.port             → listen port (default 3468)
-//
-// Env overrides take precedence so a launch script / step-4 setup can pin
-// values without touching config:
-//   MIXDOG_GATEWAY_PROVIDER, MIXDOG_GATEWAY_MODEL, MIXDOG_GATEWAY_PORT
-export function readGatewayConfig() {
-  let section = {};
-  try { section = readSection('gateway') || {}; } catch { section = {}; }
-  const mode = (typeof section.mode === 'string' ? section.mode.trim() : '') || null;
-  const inherited = mode === CLAUDE_CURRENT_MODE ? readClaudeCodeCurrentRoute() : null;
-  const provider = process.env.MIXDOG_GATEWAY_PROVIDER
-    || (inherited?.provider || '')
-    || (typeof section.defaultProvider === 'string' ? section.defaultProvider : '')
-    || null;
-  const model = process.env.MIXDOG_GATEWAY_MODEL
-    || (inherited?.model || '')
-    || (typeof section.defaultModel === 'string' ? section.defaultModel : '')
-    || null;
-  const portRaw = process.env.MIXDOG_GATEWAY_PORT || section.port;
-  const portNum = Number(portRaw);
-  const port = Number.isFinite(portNum) && portNum > 0 ? portNum : DEFAULT_GATEWAY_PORT;
-  return { provider, model, port, mode };
-}
-
-// ── Anthropic <-> common message conversion ──────────────────────────
-// The common shape consumed by provider.send() (see toOpenAIMessages in
-// providers/openai-compat.mjs and toAnthropicMessages in anthropic.mjs /
-// anthropic-oauth.mjs):
-//   • plain turn      → { role, content }                  (content is a string)
-//   • assistant w/ tools → { role:'assistant', content, toolCalls:[{id,name,arguments}] }
-//   • tool result     → { role:'tool', toolCallId, content }
-// Anthropic packs tool_result blocks inside a USER message and tool_use blocks
-// inside an ASSISTANT message; we unpack both into the per-turn common shape.
-
-// Anthropic tool_result.content is either a string or an array of content
-// blocks ({type:'text',text}, images, …). Collapse to text — the common
-// `tool` message carries a string body.
-function toolResultText(content) {
-  if (typeof content === 'string') return content;
-  if (Array.isArray(content)) {
-    return content.map(b => (b && b.type === 'text' ? (b.text || '') : '')).join('');
-  }
-  return '';
-}
-
-// Join the text blocks of an Anthropic content array into a single string.
-function textBlocksToString(blocks) {
-  return blocks.map(b => (b && b.type === 'text' ? (b.text || '') : '')).join('');
-}
-
-function toCommon(body) {
-  const out = [];
-  if (body.system) {
-    out.push({
-      role: 'system',
-      content: typeof body.system === 'string'
-        ? body.system
-        : (body.system || []).map(b => b.text || '').join('\n'),
-    });
-  }
-  for (const m of body.messages || []) {
-    // String content: pass straight through as a plain turn.
-    if (typeof m.content === 'string') {
-      out.push({ role: m.role, content: m.content });
-      continue;
-    }
-    if (!Array.isArray(m.content)) {
-      out.push({ role: m.role, content: '' });
-      continue;
-    }
-    if (m.role === 'assistant') {
-      // Collapse text blocks; lift tool_use blocks into toolCalls. send()
-      // expects toolCalls[].arguments as a PARSED object (block.input already is).
-      const text = textBlocksToString(m.content);
-      const toolCalls = m.content
-        .filter(b => b && b.type === 'tool_use')
-        .map(b => ({ id: b.id || '', name: b.name || '', arguments: b.input ?? {} }));
-      out.push({
-        role: 'assistant',
-        content: text,
-        ...(toolCalls.length ? { toolCalls } : {}),
-      });
-      continue;
-    }
-    // role === 'user' (or anything else with array content): emit each
-    // tool_result block as its own common `tool` message (provider formats
-    // demand a distinct role:'tool'/tool_result entry per result), then a
-    // user text message for any remaining text blocks.
-    const toolResults = m.content.filter(b => b && b.type === 'tool_result');
-    for (const b of toolResults) {
-      out.push({ role: 'tool', toolCallId: b.tool_use_id || '', content: toolResultText(b.content) });
-    }
-    const text = textBlocksToString(m.content);
-    if (text || toolResults.length === 0) {
-      out.push({ role: m.role, content: text });
-    }
-  }
-  return out;
-}
-
-// Anthropic tool DEFINITIONS ({name, description, input_schema}) → the common
-// tools shape send() expects ({name, description, inputSchema}); the provider
-// then re-maps via toOpenAITools / toAnthropicTools. Skips client-side tools
-// without a name. Returns undefined when there are no usable tools so send()
-// gets `undefined` (its no-tools sentinel), unchanged from step 1.
-function toCommonTools(tools) {
-  if (!Array.isArray(tools) || tools.length === 0) return undefined;
-  const mapped = tools
-    .filter(t => t && typeof t.name === 'string' && t.name)
-    .map(t => ({
-      name: t.name,
-      description: typeof t.description === 'string' ? t.description : '',
-      inputSchema: t.input_schema ?? t.inputSchema ?? { type: 'object', properties: {} },
-    }));
-  return mapped.length ? mapped : undefined;
-}
-
-// mixdog stopReason → Anthropic stop_reason.
-const STOP = { stop: 'end_turn', length: 'max_tokens', tool_calls: 'tool_use' };
-
-const sse = (res, ev, data) => res.write(`event: ${ev}\ndata: ${JSON.stringify(data)}\n\n`);
-
-function anthropicUsageFromProviderUsage(provider, usage = {}, outputOverride = null) {
-  const input = Number(usage?.inputTokens || 0) || 0;
-  const output = Number(outputOverride ?? usage?.outputTokens ?? 0) || 0;
-  const cacheRead = Number(usage?.cachedTokens ?? usage?.cacheReadTokens ?? 0) || 0;
-  const cacheWrite = Number(usage?.cacheWriteTokens || 0) || 0;
-  // Gateway responses speak Anthropic usage semantics. OpenAI/Codex/Gemini
-  // report input as an inclusive prompt total, so subtract cache slots before
-  // exposing cache_read/cache_creation; otherwise Claude-side context math
-  // would double-count cached tokens.
-  const inputTokens = isInclusiveProvider(provider)
-    ? Math.max(input - cacheRead - cacheWrite, 0)
-    : input;
-  return {
-    input_tokens: inputTokens,
-    output_tokens: output,
-    cache_read_input_tokens: cacheRead,
-    cache_creation_input_tokens: cacheWrite,
-  };
-}
-
-function readBody(req) {
-  return new Promise((resolve, reject) => {
-    let b = '';
-    let overflow = false;
-    // Cap request body. Claude Code conversation payloads can be large
-    // (full context window), so allow a generous 32 MiB before aborting.
-    const MAX_BODY_BYTES = 32 * 1024 * 1024;
-    req.on('data', (c) => {
-      if (overflow) return;
-      b += c;
-      if (b.length > MAX_BODY_BYTES) { overflow = true; reject(new Error('request body too large')); req.destroy(); }
-    });
-    req.on('end', () => { if (!overflow) resolve(b); });
-    req.on('error', reject);
-  });
-}
-
-// ── Per-request routing resolution (runtime model switching) ─────────
-// The routing target (provider + model) is re-read from config on each
-// /v1/messages request so editing gateway.defaultProvider / defaultModel
-// takes effect on the NEXT request WITHOUT restarting the gateway. A short
-// in-process TTL cache avoids hitting disk on every request under load.
-// MIXDOG_GATEWAY_PROVIDER / MIXDOG_GATEWAY_MODEL env still win (the pin is
-// applied inside readGatewayConfig). `seed` is the start-time routing, used
-// only as a fallback when a live re-read throws (transient FS error).
-const ROUTING_CACHE_TTL_MS = 1500;
-let _routingCache = null;
-let _routingCacheAt = 0;
-function getRoutingCached(seed, log = () => {}) {
-  const now = Date.now();
-  if (_routingCache && (now - _routingCacheAt) < ROUTING_CACHE_TTL_MS) return _routingCache;
-  let routing;
-  try {
-    const { provider, model, mode } = readGatewayConfig();
-    routing = { provider, model, mode };
-  } catch (e) {
-    log(`routing re-read failed, keeping previous: ${e?.message || e}`);
-    routing = _routingCache || { provider: seed?.provider ?? null, model: seed?.model ?? null, mode: seed?.mode ?? null };
-  }
-  _routingCache = routing;
-  _routingCacheAt = now;
-  return routing;
-}
-
-// Lazy provider init: if the routing target isn't registered in THIS process
-// yet (e.g. the user just switched to a provider that wasn't enabled at start),
-// re-run initProviders from the current agent config — which overlays keychain
-// keys and registers every enabled provider — then resolve again. A per-name
-// cooldown bounds repeated initProviders calls for a genuinely missing /
-// misconfigured provider so an invalid target can't thrash disk every request.
-const INIT_RETRY_COOLDOWN_MS = 2000;
-let _lastInitMissKey = null;
-let _lastInitMissAt = 0;
-async function ensureProviderInited(name, { getProviderFn, initProvidersFn, loadConfigFn, log = () => {} }) {
-  if (!name) return null;
-  let p = getProviderFn(name);
-  if (p) return p;
-  // Cooldown: don't re-init for the same missing provider within the window.
-  const now = Date.now();
-  if (_lastInitMissKey === name && (now - _lastInitMissAt) < INIT_RETRY_COOLDOWN_MS) {
-    return null;
-  }
-  try {
-    const config = loadConfigFn();
-    await initProvidersFn(config.providers);
-    p = getProviderFn(name);
-  } catch (e) {
-    log(`lazy provider init failed for "${name}": ${e?.message || e}`);
-    p = null;
-  }
-  if (!p) { _lastInitMissKey = name; _lastInitMissAt = now; }
-  return p;
-}
-
-// ── Server ───────────────────────────────────────────────────────────
-// `resolveRouting` (per-request { provider, model }) and `ensureProvider`
-// (lazy registry resolver) are injected so this handler stays testable
-// without the registry.
-function makeRequestHandler({ resolveRouting, ensureProvider, log }) {
-  return async (req, res) => {
-    // Loopback-only — belt-and-braces on top of binding to 127.0.0.1.
-    const remote = req.socket?.remoteAddress || '';
-    const isLoopback = remote === '127.0.0.1' || remote === '::1' || remote === '::ffff:127.0.0.1';
-    if (!isLoopback) {
-      res.writeHead(403, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ type: 'error', error: { type: 'permission_error', message: 'forbidden' } }));
-      return;
-    }
-    try {
-      // count_tokens: cheap char/4 estimate (no model round-trip). Must be
-      // matched BEFORE the bare /v1/messages prefix.
-      if (req.method === 'POST' && req.url.startsWith('/v1/messages/count_tokens')) {
-        const parsed = JSON.parse((await readBody(req)) || '{}');
-        const text = JSON.stringify(parsed.messages || [])
-          + (typeof parsed.system === 'string' ? parsed.system : '');
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ input_tokens: Math.ceil(text.length / 4) }));
-        return;
-      }
-      if (req.method === 'POST' && req.url.startsWith('/v1/messages')) {
-        // Re-read routing per request (runtime model switching) and lazily
-        // init the selected provider if it wasn't registered at start.
-        const routing = resolveRouting();
-        if (!routing.provider) {
-          res.writeHead(503, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({ type: 'error', error: { type: 'api_error', message: `gateway not configured (provider=${routing.provider || 'none'} model=${routing.model || 'none'})` } }));
-          return;
-        }
-        const provider = await ensureProvider(routing.provider);
-        if (!provider) {
-          res.writeHead(503, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({ type: 'error', error: { type: 'api_error', message: `gateway provider "${routing.provider}" not found or not enabled` } }));
-          return;
-        }
-        const parsed = JSON.parse((await readBody(req)) || '{}');
-        const requestRouting = routing.mode === CLAUDE_CURRENT_MODE
-          ? { ...routing, ...readClaudeCodeCurrentRoute({ request: parsed }) }
-          : routing;
-        if (!requestRouting.provider || !requestRouting.model) {
-          res.writeHead(503, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({ type: 'error', error: { type: 'api_error', message: `gateway not configured (provider=${requestRouting.provider || 'none'} model=${requestRouting.model || 'none'})` } }));
-          return;
-        }
-        const routeInfo = readGatewayRouteInfo(requestRouting, provider);
-        const messages = toCommon(parsed);
-        const sendTools = toCommonTools(parsed.tools);
-        const prepared = prepareGatewayMessages(messages, sendTools, routeInfo, log);
-        const usageSnapshotP = fetchOAuthUsageSnapshot(routeInfo, provider, log).catch(() => null);
-        if (prepared.trim?.overflow === true) {
-          updateGatewayAdvert(
-            routeInfo,
-            {
-              at: Date.now(),
-              provider: routeInfo.provider,
-              model: routeInfo.model,
-              responseModel: routeInfo.model,
-              inputTokens: 0,
-              outputTokens: 0,
-              cacheReadTokens: 0,
-              cacheWriteTokens: 0,
-              promptTokens: prepared.trim.beforeTokens || 0,
-              costUsd: 0,
-              costSource: 'none',
-              contextUsedPct: routeInfo.contextWindow ? Math.round((prepared.trim.beforeTokens || 0) * 10000 / routeInfo.contextWindow) / 100 : null,
-              trim: prepared.trim,
-              durationMs: 0,
-              rawUsageKeys: [],
-            },
-            null,
-            log,
-          );
-          res.writeHead(413, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify({
-            type: 'error',
-            error: {
-              type: 'invalid_request_error',
-              message: `gateway target context overflow for ${routeInfo.provider}/${routeInfo.model}: estimated ${prepared.trim.beforeTokens} tokens exceeds safe budget ${prepared.trim.budgetTokens}`,
-            },
-          }));
-          return;
-        }
-        const wantStream = parsed.stream === true;
-        const id = 'msg_' + Date.now().toString(36);
-        const startedAt = Date.now();
-        const out = await provider.send(prepared.messages, routeInfo.model || routing.model, sendTools, gatewaySendOptions(routeInfo));
-        const responseModel = out.model || routeInfo.model || routing.model;
-        const textOut = out.content || '';
-        // send() returns toolCalls as [{ id, name, arguments }] (arguments is
-        // a PARSED object — see parseToolCalls in openai-compat.mjs and the
-        // tool_use assembly in anthropic-oauth.mjs parseSSEStream). Map each
-        // into an Anthropic tool_use block ({ type, id, name, input }).
-        const toolCalls = Array.isArray(out.toolCalls) ? out.toolCalls : [];
-        // If the model emitted tool calls but the provider didn't flag the
-        // stop reason as tool_calls, force tool_use so the client knows to run
-        // them and continue the turn.
-        const stop = toolCalls.length ? 'tool_use' : (STOP[out.stopReason] || 'end_turn');
-        const usage = anthropicUsageFromProviderUsage(routeInfo.provider, out.usage);
-        const usageSummary = summarizeGatewayUsage(routeInfo, out, prepared.trim, Date.now() - startedAt);
-        recordGatewayUsageEvent(usageSummary);
-        const usageSnapshot = await usageSnapshotP;
-        const limits = buildGatewayLimits(routeInfo, out, usageSnapshot);
-        updateGatewayAdvert(routeInfo, usageSummary, limits, log);
-        log(`route -> ${routeInfo.provider}/${routeInfo.model} ${textOut.length}chars tools=${sendTools ? sendTools.length : 0} toolCalls=${toolCalls.length} stream=${wantStream} model=${responseModel}`);
-        const routeHeaders = {
-          'x-mixdog-provider': routeInfo.provider || '',
-          'x-mixdog-model': routeInfo.model || '',
-        };
-        if (!wantStream) {
-          // content = optional leading text block, then one tool_use block per call.
-          const content = [];
-          if (textOut) content.push({ type: 'text', text: textOut });
-          for (const tc of toolCalls) {
-            content.push({ type: 'tool_use', id: tc.id, name: tc.name, input: tc.arguments ?? {} });
-          }
-          if (content.length === 0) content.push({ type: 'text', text: '' });
-          res.writeHead(200, { 'Content-Type': 'application/json', ...routeHeaders });
-          res.end(JSON.stringify({
-            id, type: 'message', role: 'assistant',
-            model: responseModel,
-            content,
-            stop_reason: stop, stop_sequence: null, usage,
-          }));
-          return;
-        }
-        // Pseudo-stream: assembled reply chunked back as Anthropic SSE.
-        res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', ...routeHeaders });
-        sse(res, 'message_start', { type: 'message_start', message: { id, type: 'message', role: 'assistant', model: responseModel, content: [], stop_reason: null, stop_sequence: null, usage: anthropicUsageFromProviderUsage(routeInfo.provider, out.usage, 0) } });
-        // Block 0: text (always emitted, even when empty, so the index space
-        // is stable). Chunk the assembled text as text_delta — pseudo-stream.
-        let blockIndex = 0;
-        sse(res, 'content_block_start', { type: 'content_block_start', index: blockIndex, content_block: { type: 'text', text: '' } });
-        const ch = Math.max(1, Math.ceil(textOut.length / 6));
-        for (let i = 0; i < textOut.length; i += ch) {
-          sse(res, 'content_block_delta', { type: 'content_block_delta', index: blockIndex, delta: { type: 'text_delta', text: textOut.slice(i, i + ch) } });
-        }
-        sse(res, 'content_block_stop', { type: 'content_block_stop', index: blockIndex });
-        // One tool_use block per call: content_block_start{tool_use} →
-        // input_json_delta{partial_json:<full json at once>} → content_block_stop.
-        // This is the reverse of anthropic-oauth.mjs parseSSEStream's tool_use
-        // assembly (which concatenates input_json_delta into inputJson then
-        // JSON.parses at content_block_stop).
-        for (const tc of toolCalls) {
-          blockIndex += 1;
-          sse(res, 'content_block_start', { type: 'content_block_start', index: blockIndex, content_block: { type: 'tool_use', id: tc.id, name: tc.name, input: {} } });
-          sse(res, 'content_block_delta', { type: 'content_block_delta', index: blockIndex, delta: { type: 'input_json_delta', partial_json: JSON.stringify(tc.arguments ?? {}) } });
-          sse(res, 'content_block_stop', { type: 'content_block_stop', index: blockIndex });
-        }
-        sse(res, 'message_delta', { type: 'message_delta', delta: { stop_reason: stop, stop_sequence: null }, usage: { output_tokens: usage.output_tokens } });
-        sse(res, 'message_stop', { type: 'message_stop' });
-        res.end();
-        return;
-      }
-      // HEAD / and any other path: best-effort empty JSON so client
-      // bootstrap probes (models, capabilities, …) don't error out.
-      await readBody(req).catch(() => {});
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end('{}');
-    } catch (e) {
-      log(`ERROR ${e?.message || e}`);
-      if (!res.headersSent) {
-        res.writeHead(500, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ type: 'error', error: { type: 'api_error', message: String(e?.message || e) } }));
-      } else {
-        try { res.end(); } catch {}
-      }
-    }
-  };
-}
-
-/**
- * Start the gateway HTTP server.
- *
- * @param {object}   opts
- * @param {string}   opts.provider     routing target provider (registry key)
- * @param {string}   opts.model        model id passed to provider.send()
- * @param {number}   [opts.port]       listen port (default 3468)
- * @param {string}   [opts.host]       bind host (default 127.0.0.1)
- * @param {function} [opts.getProviderFn]   provider resolver (defaults to registry.getProvider)
- * @param {function} [opts.initProvidersFn] (re)init registry for lazy provider load (defaults to registry.initProviders)
- * @param {function} [opts.loadConfigFn]    agent config loader for lazy init (defaults to config.loadConfig)
- * @param {function} [opts.log]        line logger
- * @returns {Promise<{ port:number, close:()=>Promise<void> }>}
- */
-export async function startGatewayServer({ provider, model, mode = null, port = DEFAULT_GATEWAY_PORT, host = GATEWAY_HOST, getProviderFn, initProvidersFn, loadConfigFn, log = () => {} } = {}) {
-  // Lazily import the registry/config so import-only consumers (tests) that
-  // inject their own fns never pull the provider tree in.
-  if (!getProviderFn || !initProvidersFn || !loadConfigFn) {
-    const reg = await import('../agent/orchestrator/providers/registry.mjs');
-    const cfg = await import('../agent/orchestrator/config.mjs');
-    getProviderFn = getProviderFn || reg.getProvider;
-    initProvidersFn = initProvidersFn || reg.initProviders;
-    loadConfigFn = loadConfigFn || cfg.loadConfig;
-  }
-  // Seed routing from the start-time args; the handler re-reads config per
-  // request via getRoutingCached (runtime model switching) and falls back to
-  // this seed only when a live re-read throws.
-  const seed = { provider, model, mode };
-  const resolveRouting = () => getRoutingCached(seed, log);
-  const ensureProvider = (name) => ensureProviderInited(name, { getProviderFn, initProvidersFn, loadConfigFn, log });
-  const server = http.createServer(makeRequestHandler({ resolveRouting, ensureProvider, log }));
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(port, host, () => { server.removeListener('error', reject); resolve(); });
-  });
-  const address = server.address();
-  const boundPort = typeof address === 'object' && address ? address.port : port;
-  log(`listening on ${host}:${boundPort} provider=${provider} model=${model}`);
-  return {
-    port: boundPort,
-    close: () => new Promise((resolve) => server.close(() => resolve())),
-  };
-}
-
-// ── active-instance.json advertisement ───────────────────────────────
-// Mirrors advertiseMemoryPort() in src/memory/index.mjs: atomically merge
-// gateway_port + gateway_server_pid into the shared active-instance.json so
-// hooks / setup / status discovery can find the gateway without a hard-coded
-// port. A periodic re-advertise (every 30s) recovers from external file
-// truncation, matching the memory worker's behavior.
-let _periodicAdvertiseInstalled = false;
-let _currentAdvertisedPort = null;
-function cleanGatewayFields(cur) {
-  return Object.fromEntries(
-    Object.entries(cur || {}).filter(([key]) => !key.startsWith('gateway_'))
-  );
-}
-
-function currentRouteAdvertFields(boundPort, log = () => {}) {
-  try {
-    const routeInfo = readGatewayRouteInfo(readGatewayConfig());
-    const usageSnapshot = readCachedOAuthUsageSnapshot(routeInfo);
-    return gatewayAdvertFields(routeInfo, null, buildGatewayLimits(routeInfo, null, usageSnapshot));
-  } catch (e) {
-    log(`gateway metadata read failed: ${e?.message || e}`);
-    return {};
-  }
-}
-
-function updateGatewayAdvert(routeInfo, usageSummary = null, limits = null, log = () => {}) {
-  if (!Number.isFinite(_currentAdvertisedPort) || _currentAdvertisedPort <= 0) return;
-  try {
-    const fields = gatewayAdvertFields(routeInfo, usageSummary, limits);
-    updateJsonAtomicSync(ACTIVE_INSTANCE_FILE, (curRaw) => {
-      const cur = curRaw ?? {};
-      const curGwPid = parsePositivePid(cur?.gateway_server_pid);
-      if (curGwPid != null && curGwPid !== GATEWAY_SERVER_PID && isPidAlive(curGwPid)) {
-        return undefined;
-      }
-      return {
-        ...cur,
-        gateway_port: _currentAdvertisedPort,
-        ...(GATEWAY_SERVER_PID ? { gateway_server_pid: GATEWAY_SERVER_PID } : {}),
-        ...fields,
-        updatedAt: Date.now(),
-      };
-    }, { compact: true, fsyncDir: true });
-  } catch (e) {
-    log(`active-instance gateway metadata update failed: ${e?.message || e}`);
-  }
-}
-
-function advertiseGatewayPort(boundPort, attempt = 0, log = () => {}) {
-  if (!Number.isFinite(boundPort) || boundPort <= 0) return;
-  _currentAdvertisedPort = boundPort;
-  try {
-    const routeFields = currentRouteAdvertFields(boundPort, log);
-    updateJsonAtomicSync(ACTIVE_INSTANCE_FILE, (curRaw) => {
-      const cur = curRaw ?? {};
-      // Owner guard (symmetric with unadvertiseGatewayPort): if a DIFFERENT
-      // gateway_server_pid is already advertised AND that process is still
-      // alive, yield to the live owner rather than clobbering its entry.
-      // Mirrors the memory_port conflict check in server-main.mjs.
-      const curGwPort = Number(cur?.gateway_port);
-      const curGwPid = parsePositivePid(cur?.gateway_server_pid);
-      const portConflict = Number.isFinite(curGwPort) && curGwPort > 0 && curGwPort !== boundPort;
-      const otherOwnerAlive = curGwPid != null && curGwPid !== GATEWAY_SERVER_PID && isPidAlive(curGwPid);
-      if (portConflict && otherOwnerAlive) {
-        log(`skip gateway_port advertise port=${boundPort} curGwPort=${curGwPort} curGwPid=${curGwPid} gatewayServerPid=${GATEWAY_SERVER_PID || 'none'}`);
-        return undefined;
-      }
-      return {
-        ...cur,
-        gateway_port: boundPort,
-        ...(GATEWAY_SERVER_PID ? { gateway_server_pid: GATEWAY_SERVER_PID } : {}),
-        ...routeFields,
-        updatedAt: Date.now(),
-      };
-    }, { compact: true, fsyncDir: true });
-    if (!_periodicAdvertiseInstalled) {
-      _periodicAdvertiseInstalled = true;
-      setInterval(() => {
-        try { if (_currentAdvertisedPort != null) advertiseGatewayPort(_currentAdvertisedPort, 0, log); } catch {}
-      }, 30_000).unref?.();
-    }
-  } catch (e) {
-    const transient = e?.code === 'EPERM' || e?.code === 'EBUSY' || e?.code === 'EACCES';
-    if (transient && attempt < 3) {
-      setTimeout(() => advertiseGatewayPort(boundPort, attempt + 1, log), 50 * (attempt + 1));
-      return;
-    }
-    log(`active-instance gateway_port advertise failed: ${e?.message || e}`);
-  }
-}
-
-function unadvertiseGatewayPort(log = () => {}) {
-  try {
-    updateJsonAtomicSync(ACTIVE_INSTANCE_FILE, (curRaw) => {
-      const cur = curRaw ?? {};
-      // Only retract OUR advertisement. A different live gateway owner that
-      // raced in between must not have its port clobbered to null.
-      if (parsePositivePid(cur.gateway_server_pid) && parsePositivePid(cur.gateway_server_pid) !== GATEWAY_SERVER_PID) {
-        return undefined;
-      }
-      const rest = cleanGatewayFields(cur);
-      return { ...rest, updatedAt: Date.now() };
-    }, { compact: true, fsyncDir: true });
-  } catch (e) {
-    log(`active-instance gateway_port retract failed: ${e?.message || e}`);
-  }
-}
-
-// ── Child-process entry point ─────────────────────────────────────────
-// When forked directly (`node src/gateway/server.mjs`), read config from
-// the agent config + MIXDOG_GATEWAY_* env, init the provider registry, bind
-// the fixed port, and advertise it. Parent signals shutdown via IPC
-// disconnect or SIGTERM.
-const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
-if (isMain) {
-  const log = (m) => process.stdout.write(`[gateway] ${m}\n`);
-  const { provider, model, port, mode } = readGatewayConfig();
-  if (!provider || !model) {
-    // Enabled-but-unconfigured: no-op. Exit cleanly so the parent does not
-    // treat it as a crash to respawn forever.
-    log(`no defaultProvider/defaultModel configured (provider=${provider || 'none'} model=${model || 'none'}) — gateway idle, exiting`);
-    process.exit(0);
-  }
-
-  let handle = null;
-  let shuttingDown = false;
-  const shutdown = async (reason) => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    log(`shutdown (${reason})`);
-    try { unadvertiseGatewayPort(log); } catch {}
-    try { if (handle) await handle.close(); } catch {}
-    process.exit(0);
-  };
-  process.on('SIGTERM', () => shutdown('SIGTERM'));
-  process.on('SIGINT', () => shutdown('SIGINT'));
-  process.on('disconnect', () => shutdown('parent-disconnect'));
-  process.on('message', (msg) => { if (msg?.type === 'shutdown') shutdown('ipc-shutdown'); });
-
-  try {
-    // Init the provider registry IN THIS PROCESS — the gateway child is
-    // separate from the MCP parent where the agent module runs. loadConfig()
-    // overlays keychain API keys onto the provider config, exactly like the
-    // agent module's reloadAgentConfig() path.
-    const { loadConfig } = await import('../agent/orchestrator/config.mjs');
-    const { initProviders, getProvider } = await import('../agent/orchestrator/providers/registry.mjs');
-    const config = loadConfig();
-    await initProviders(config.providers);
-    if (!getProvider(provider)) {
-      log(`provider "${provider}" not enabled in agent config — gateway idle, exiting`);
-      process.exit(0);
-    }
-    // Pass the registry/config fns so the handler's per-request routing
-    // re-read + lazy provider init (runtime model switching) reuse the same
-    // already-imported singletons rather than re-importing per request.
-    handle = await startGatewayServer({
-      provider, model, port, mode,
-      getProviderFn: getProvider,
-      initProvidersFn: initProviders,
-      loadConfigFn: loadConfig,
-      log,
-    });
-    advertiseGatewayPort(handle.port, 0, log);
-    try { process.send?.({ type: 'gateway_ready', port: handle.port }); } catch {}
-  } catch (e) {
-    // First-binder-wins: EADDRINUSE means another server-main already hosts
-    // the gateway on this port (multi-instance). Yield as idle (exit 0) so the
-    // parent's exit handler does NOT crash-restart loop. Other listen/init
-    // errors are real failures → exit 1 (parent restarts with backoff).
-    if (e && e.code === 'EADDRINUSE') {
-      log(`port ${port} already in use — another gateway owner is active; idle, exiting`);
-      process.exit(0);
-    }
-    log(`failed to start: ${e && (e.stack || e.message) || e}`);
-    process.exit(1);
-  }
-}