mixdog 0.7.17 → 0.7.18

package/src/gateway/server.mjs

@@ -0,0 +1,713 @@
+/**
+ * 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);
+  }
+}