@kb-labs/gateway-app 0.2.0 → 0.3.0

package/dist/index.js

@@ -0,0 +1,2454 @@
+import { logDiagnosticEvent } from '@kb-labs/core-platform';
+import { createServiceBootstrap, platform } from '@kb-labs/core-runtime';
+import { createCorrelatedLogger, registerOpenAPI, createServiceReadyResponse, OperationMetricsTracker, createServiceObservabilityDescribe, createServiceObservabilityHealth } from '@kb-labs/shared-http';
+import { SqliteHostStore, globalDispatcher, AdaptiveBuffer } from '@kb-labs/gateway-core';
+import { findNearestConfig, readJsonWithDiagnostics } from '@kb-labs/core-config';
+import { GatewayConfigSchema, HostRegistrationSchema, RegisterRequestSchema, TokenRequestSchema, RefreshRequestSchema, ExecuteRequestSchema, ChatCompletionRequestSchema, TelemetryIngestRequestSchema, PlatformCallRequestSchema, HelloMessageSchema, SUPPORTED_PROTOCOL_VERSIONS, HostCapabilitySchema, AdapterCallMessageSchema, AdapterNameSchema, ClientHelloSchema, ClientCancelSchema, ClientUnsubscribeSchema, ClientSubscribeSchema, CLIENT_PROTOCOL_VERSION } from '@kb-labs/gateway-contracts';
+import Fastify from 'fastify';
+import fastifyCors from '@fastify/cors';
+import fastifyHttpProxy from '@fastify/http-proxy';
+import { AuthService, getClientByHostId } from '@kb-labs/gateway-auth';
+import { randomUUID } from 'crypto';
+import { mergeOpenAPISpecs } from '@kb-labs/core-registry';
+import { WebSocketServer } from 'ws';
+import { CANONICAL_OBSERVABILITY_METRICS, OBSERVABILITY_CONTRACT_VERSION, OBSERVABILITY_SCHEMA } from '@kb-labs/core-contracts';
+import { hostname } from 'os';
+import { monitorEventLoopDelay, performance } from 'perf_hooks';
+
+// src/bootstrap.ts
+async function loadGatewayConfig(repoRoot) {
+  const { path: configPath } = await findNearestConfig({
+    startDir: repoRoot,
+    filenames: [".kb/kb.config.json", "kb.config.json"]
+  });
+  if (!configPath) {
+    return GatewayConfigSchema.parse({});
+  }
+  const result = await readJsonWithDiagnostics(configPath);
+  if (!result.ok || !result.data.gateway) {
+    return GatewayConfigSchema.parse({});
+  }
+  return GatewayConfigSchema.parse(result.data.gateway);
+}
+async function resolveToken(token, cache, jwtConfig) {
+  const authService = new AuthService(cache, jwtConfig);
+  const jwtContext = await authService.verify(token);
+  if (jwtContext) {
+    return jwtContext;
+  }
+  const machineEntry = await cache.get(
+    `host:token:${token}`
+  );
+  if (machineEntry) {
+    return {
+      type: "machine",
+      userId: machineEntry.hostId,
+      namespaceId: machineEntry.namespaceId,
+      tier: "free",
+      permissions: ["host:connect"]
+    };
+  }
+  return null;
+}
+function extractBearerToken(authHeader) {
+  if (!authHeader) {
+    return null;
+  }
+  const match = authHeader.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1] ?? null : null;
+}
+
+// src/auth/middleware.ts
+var PUBLIC_ROUTES = /* @__PURE__ */ new Set([
+  "/health",
+  "/hosts/register",
+  // /hosts/connect and /clients/connect are handled at the HTTP upgrade level
+  // by gateway-ws.ts (raw ws) — they never reach Fastify routing.
+  "/auth/register",
+  "/auth/token",
+  "/auth/refresh",
+  "/internal/dispatch",
+  // has its own x-internal-secret auth
+  "/internal/resolve-host"
+  // has its own x-internal-secret auth
+]);
+function createAuthMiddleware(cache, jwtConfig) {
+  return async function authMiddleware(request, reply) {
+    const rawPath = new URL(request.url, "http://localhost").pathname;
+    const routePath = rawPath.replace(/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (PUBLIC_ROUTES.has(routePath)) {
+      return;
+    }
+    const queryToken = request.query["access_token"];
+    const token = extractBearerToken(request.headers.authorization) ?? queryToken ?? null;
+    if (!token) {
+      return reply.code(401).send({ error: "Unauthorized", message: "Missing Authorization header" });
+    }
+    const authContext = await resolveToken(token, cache, jwtConfig);
+    if (!authContext) {
+      return reply.code(401).send({ error: "Unauthorized", message: "Invalid token" });
+    }
+    request.authContext = authContext;
+  };
+}
+function registerAuthRoutes(app, authService) {
+  app.post("/auth/register", { schema: { tags: ["Auth"], summary: "Register new agent and get credentials" } }, async (request, reply) => {
+    const parsed = RegisterRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: "Bad Request", issues: parsed.error.issues });
+    }
+    const result = await authService.register(parsed.data);
+    return reply.code(201).send(result);
+  });
+  app.post("/auth/token", { schema: { tags: ["Auth"], summary: "Issue JWT token pair" } }, async (request, reply) => {
+    const parsed = TokenRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: "Bad Request", issues: parsed.error.issues });
+    }
+    const tokens = await authService.issueTokens(parsed.data.clientId, parsed.data.clientSecret);
+    if (!tokens) {
+      return reply.code(401).send({ error: "Unauthorized", message: "Invalid credentials" });
+    }
+    return reply.send(tokens);
+  });
+  app.post("/auth/refresh", { schema: { tags: ["Auth"], summary: "Refresh JWT token pair" } }, async (request, reply) => {
+    const parsed = RefreshRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: "Bad Request", issues: parsed.error.issues });
+    }
+    const tokens = await authService.refreshTokens(parsed.data.refreshToken);
+    if (!tokens) {
+      return reply.code(401).send({ error: "Unauthorized", message: "Invalid or expired refresh token" });
+    }
+    return reply.send(tokens);
+  });
+}
+
+// src/execute/execution-registry.ts
+var ExecutionRegistry = class {
+  executions = /* @__PURE__ */ new Map();
+  /** Register a new execution. Returns AbortSignal to wire into the dispatch. */
+  register(entry) {
+    const controller = new AbortController();
+    this.executions.set(entry.executionId, {
+      ...entry,
+      controller,
+      startedAt: Date.now()
+    });
+    return controller.signal;
+  }
+  /** Cancel an execution by ID. Returns true if found and aborted. */
+  cancel(executionId, reason) {
+    const entry = this.executions.get(executionId);
+    if (!entry) {
+      return false;
+    }
+    if (entry.controller.signal.aborted) {
+      return false;
+    }
+    entry.cancelledReason = reason;
+    entry.controller.abort(reason);
+    return true;
+  }
+  /** Remove a completed/cancelled execution. */
+  remove(executionId) {
+    this.executions.delete(executionId);
+  }
+  /** Get an active execution. */
+  get(executionId) {
+    return this.executions.get(executionId);
+  }
+  /** Cancel all executions dispatched to a host (on host disconnect). */
+  cancelByHost(hostId, reason) {
+    const cancelled = [];
+    for (const entry of this.executions.values()) {
+      if (entry.hostId === hostId && !entry.controller.signal.aborted) {
+        entry.cancelledReason = reason;
+        entry.controller.abort(reason);
+        cancelled.push(entry.executionId);
+      }
+    }
+    return cancelled;
+  }
+  /** Number of active executions. */
+  get size() {
+    return this.executions.size;
+  }
+};
+var executionRegistry = new ExecutionRegistry();
+
+// src/clients/subscription-registry.ts
+var SubscriptionRegistry = class {
+  /** executionId → Set<connectionId> */
+  byExecution = /* @__PURE__ */ new Map();
+  /** connectionId → Set<executionId> */
+  byConnection = /* @__PURE__ */ new Map();
+  /** connectionId → WebSocket (for sending events) */
+  sockets = /* @__PURE__ */ new Map();
+  /** Register a WebSocket for a connection. Must be called before subscribe(). */
+  registerSocket(connectionId, socket) {
+    this.sockets.set(connectionId, socket);
+  }
+  /** Remove a connection's socket on disconnect. */
+  removeSocket(connectionId) {
+    this.sockets.delete(connectionId);
+  }
+  subscribe(connectionId, executionId) {
+    let executionSubs = this.byExecution.get(executionId);
+    if (!executionSubs) {
+      executionSubs = /* @__PURE__ */ new Set();
+      this.byExecution.set(executionId, executionSubs);
+    }
+    executionSubs.add(connectionId);
+    let connectionSubs = this.byConnection.get(connectionId);
+    if (!connectionSubs) {
+      connectionSubs = /* @__PURE__ */ new Set();
+      this.byConnection.set(connectionId, connectionSubs);
+    }
+    connectionSubs.add(executionId);
+  }
+  unsubscribe(connectionId, executionId) {
+    this.byExecution.get(executionId)?.delete(connectionId);
+    this.byConnection.get(connectionId)?.delete(executionId);
+    if (this.byExecution.get(executionId)?.size === 0) {
+      this.byExecution.delete(executionId);
+    }
+    if (this.byConnection.get(connectionId)?.size === 0) {
+      this.byConnection.delete(connectionId);
+    }
+  }
+  getSubscribers(executionId) {
+    return this.byExecution.get(executionId) ?? /* @__PURE__ */ new Set();
+  }
+  getSubscriptions(connectionId) {
+    return this.byConnection.get(connectionId) ?? /* @__PURE__ */ new Set();
+  }
+  removeConnection(connectionId) {
+    const subscriptions = this.byConnection.get(connectionId);
+    if (!subscriptions) {
+      this.sockets.delete(connectionId);
+      return [];
+    }
+    const orphaned = [];
+    for (const executionId of subscriptions) {
+      const subs = this.byExecution.get(executionId);
+      if (subs) {
+        subs.delete(connectionId);
+        if (subs.size === 0) {
+          this.byExecution.delete(executionId);
+          orphaned.push(executionId);
+        }
+      }
+    }
+    this.byConnection.delete(connectionId);
+    this.sockets.delete(connectionId);
+    return orphaned;
+  }
+  broadcast(executionId, event) {
+    const subscribers = this.byExecution.get(executionId);
+    if (!subscribers || subscribers.size === 0) {
+      return;
+    }
+    const payload = JSON.stringify(event);
+    for (const connectionId of subscribers) {
+      const socket = this.sockets.get(connectionId);
+      if (socket && socket.readyState === socket.OPEN) {
+        socket.send(payload);
+      }
+    }
+  }
+  get connectionCount() {
+    return this.byConnection.size;
+  }
+  get subscriptionCount() {
+    let total = 0;
+    for (const subs of this.byExecution.values()) {
+      total += subs.size;
+    }
+    return total;
+  }
+};
+var subscriptionRegistry = new SubscriptionRegistry();
+
+// src/execute/errors.ts
+var CancelledError = class extends Error {
+  reason;
+  constructor(reason) {
+    super(`Execution cancelled: ${reason}`);
+    this.name = "CancelledError";
+    this.reason = reason;
+  }
+};
+
+// src/execute/retry-executor.ts
+var DEFAULTS = {
+  maxAttempts: 1,
+  initialDelayMs: 1e3,
+  backoffMultiplier: 2,
+  maxDelayMs: 3e4,
+  onlyRetryable: true
+};
+async function executeWithRetry(ctx, dispatch) {
+  const cfg = { ...DEFAULTS, ...ctx.config };
+  const maxAttempts = Math.max(1, cfg.maxAttempts);
+  let lastError = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (ctx.signal.aborted) {
+      throw new CancelledError(ctx.signal.reason);
+    }
+    try {
+      return await raceAbort(ctx.signal, dispatch());
+    } catch (err) {
+      if (err instanceof CancelledError) {
+        throw err;
+      }
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt >= maxAttempts) {
+        break;
+      }
+      const classified = classifyError(err);
+      if (cfg.onlyRetryable && !classified.retryable) {
+        break;
+      }
+      const delay = Math.min(
+        cfg.initialDelayMs * Math.pow(cfg.backoffMultiplier, attempt - 1),
+        cfg.maxDelayMs
+      );
+      ctx.write({
+        type: "execution:retry",
+        requestId: ctx.requestId,
+        executionId: ctx.executionId,
+        attempt,
+        maxAttempts,
+        delayMs: delay,
+        error: classified.message
+      });
+      await interruptibleDelay(delay, ctx.signal);
+    }
+  }
+  throw lastError ?? new Error("executeWithRetry: no attempts made");
+}
+function raceAbort(signal, promise) {
+  if (signal.aborted) {
+    return Promise.reject(new CancelledError(signal.reason));
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(new CancelledError(signal.reason));
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (v) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(v);
+      },
+      (e) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(e);
+      }
+    );
+  });
+}
+function interruptibleDelay(ms, signal) {
+  if (signal.aborted) {
+    return Promise.reject(new CancelledError(signal.reason));
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new CancelledError(signal.reason));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function classifyError(err) {
+  if (!(err instanceof Error)) {
+    return { code: "UNKNOWN", message: String(err), retryable: false };
+  }
+  const msg = err.message;
+  if (msg.includes("ECONNREFUSED") || msg.includes("ECONNRESET") || msg.includes("ETIMEDOUT") || msg.includes("timed out") || msg.includes("503") || msg.includes("Service Unavailable")) {
+    return { code: "TRANSPORT_ERROR", message: msg, retryable: true };
+  }
+  if (msg.includes("Host not connected")) {
+    return { code: "HOST_UNAVAILABLE", message: msg, retryable: true };
+  }
+  return { code: "HANDLER_ERROR", message: msg, retryable: false };
+}
+
+// src/execute/routes.ts
+function registerExecuteRoutes(app, logger) {
+  app.post("/api/v1/execute", { schema: { tags: ["Execute"], summary: "Execute a plugin handler", hide: true } }, async (request, reply) => {
+    const auth = request.authContext;
+    if (!auth) {
+      return reply.code(401).send({ error: "Unauthorized" });
+    }
+    const parsed = ExecuteRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: "Bad Request", issues: parsed.error.issues });
+    }
+    const { pluginId, handlerRef, exportName, input, timeoutMs } = parsed.data;
+    const executionId = randomUUID();
+    const requestId = randomUUID();
+    const startTime = Date.now();
+    logger.info("Execute request received", {
+      executionId,
+      pluginId,
+      handlerRef,
+      namespaceId: auth.namespaceId
+    });
+    const hostId = globalDispatcher.firstHostWithCapability(auth.namespaceId, "execution");
+    if (!hostId) {
+      logDiagnosticEvent(logger, {
+        domain: "service",
+        event: "gateway.execution.dispatch",
+        level: "warn",
+        reasonCode: "execution_host_unavailable",
+        message: "No execution host connected for namespace",
+        outcome: "failed",
+        serviceId: "gateway",
+        evidence: {
+          namespaceId: auth.namespaceId,
+          pluginId,
+          handlerRef
+        }
+      });
+      return reply.code(503).send({
+        error: "No execution host connected",
+        hint: "Ensure a RuntimeServer is running and connected to Gateway",
+        namespaceId: auth.namespaceId
+      });
+    }
+    const signal = executionRegistry.register({
+      executionId,
+      requestId,
+      namespaceId: auth.namespaceId,
+      hostId,
+      pluginId,
+      handlerRef
+    });
+    reply.raw.on("close", () => {
+      if (!reply.raw.writableFinished && !signal.aborted) {
+        executionRegistry.cancel(executionId, "disconnect");
+      }
+    });
+    reply.raw.writeHead(200, {
+      "Content-Type": "application/x-ndjson",
+      "Transfer-Encoding": "chunked",
+      "Cache-Control": "no-cache",
+      "X-Execution-Id": executionId
+    });
+    reply.raw.flushHeaders();
+    const writeEvent = (event) => {
+      const payload = JSON.stringify(event) + "\n";
+      if (!reply.raw.writableEnded) {
+        reply.raw.write(payload);
+      }
+      subscriptionRegistry.broadcast(executionId, event);
+    };
+    try {
+      const result = await executeWithRetry(
+        { executionId, requestId, signal, config: void 0, write: writeEvent },
+        () => globalDispatcher.call(
+          auth.namespaceId,
+          hostId,
+          "execution",
+          "execute",
+          [{ pluginId, handlerRef, exportName, input, executionId, requestId, timeoutMs }]
+        )
+      );
+      writeEvent({
+        type: "execution:done",
+        requestId,
+        executionId,
+        exitCode: 0,
+        durationMs: Date.now() - startTime,
+        metadata: { result }
+      });
+    } catch (err) {
+      if (err instanceof CancelledError) {
+        writeEvent({
+          type: "execution:cancelled",
+          requestId,
+          executionId,
+          reason: err.reason ?? "user",
+          durationMs: Date.now() - startTime
+        });
+        writeEvent({
+          type: "execution:done",
+          requestId,
+          executionId,
+          exitCode: 130,
+          durationMs: Date.now() - startTime
+        });
+      } else {
+        const message = err instanceof Error ? err.message : String(err);
+        logDiagnosticEvent(logger, {
+          domain: "service",
+          event: "gateway.execution.dispatch",
+          level: "error",
+          reasonCode: "execution_dispatch_failed",
+          message: "Gateway execution dispatch failed",
+          outcome: "failed",
+          error: err instanceof Error ? err : new Error(String(err)),
+          serviceId: "gateway",
+          evidence: {
+            namespaceId: auth.namespaceId,
+            executionId,
+            requestId,
+            pluginId,
+            handlerRef,
+            hostId
+          }
+        });
+        writeEvent({
+          type: "execution:error",
+          requestId,
+          executionId,
+          code: "EXECUTION_FAILED",
+          message,
+          retryable: false
+        });
+        writeEvent({
+          type: "execution:done",
+          requestId,
+          executionId,
+          exitCode: 1,
+          durationMs: Date.now() - startTime
+        });
+      }
+    } finally {
+      executionRegistry.remove(executionId);
+      if (!reply.raw.writableEnded) {
+        reply.raw.end();
+      }
+    }
+  });
+  app.post("/api/v1/execute/:executionId/cancel", { schema: { tags: ["Execute"], summary: "Cancel an active execution" } }, async (request, reply) => {
+    const auth = request.authContext;
+    if (!auth) {
+      return reply.code(401).send({ error: "Unauthorized" });
+    }
+    const { executionId } = request.params;
+    const body = request.body;
+    const reason = body?.reason ?? "user";
+    const execution = executionRegistry.get(executionId);
+    if (!execution) {
+      return reply.code(404).send({ error: "Execution not found or already completed" });
+    }
+    if (execution.namespaceId !== auth.namespaceId) {
+      return reply.code(403).send({ error: "Forbidden \u2014 execution belongs to another namespace" });
+    }
+    const cancelled = executionRegistry.cancel(executionId, reason);
+    logger.info("Cancel request processed", {
+      executionId,
+      reason,
+      cancelled,
+      namespaceId: auth.namespaceId
+    });
+    return reply.code(cancelled ? 200 : 409).send({
+      executionId,
+      status: cancelled ? "cancelled" : "already_cancelled",
+      reason
+    });
+  });
+}
+function isLLMRouter(llm) {
+  return typeof llm.resolveAdapter === "function";
+}
+async function resolveLLMForTier(tier) {
+  const llm = platform.llm;
+  if (!llm) {
+    return void 0;
+  }
+  if (isLLMRouter(llm)) {
+    const binding = await llm.resolveAdapter({ tier });
+    return binding.adapter;
+  }
+  return llm;
+}
+function registerLLMGatewayRoutes(app, logger) {
+  app.post("/llm/v1/chat/completions", { schema: { tags: ["LLM"], summary: "OpenAI-compatible chat completions", hide: true } }, async (request, reply) => {
+    const auth = request.authContext;
+    if (!auth) {
+      return reply.code(401).send({ error: "Unauthorized" });
+    }
+    const parsed = ChatCompletionRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({
+        error: {
+          message: "Bad Request",
+          type: "invalid_request_error",
+          code: null,
+          param: null
+        },
+        issues: parsed.error.issues
+      });
+    }
+    const req = parsed.data;
+    const requestId = `chatcmpl-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const llm = await resolveLLMForTier(req.model);
+    if (!llm) {
+      return reply.code(503).send({
+        error: {
+          message: `LLM not available for tier "${req.model}"`,
+          type: "server_error",
+          code: null,
+          param: null
+        }
+      });
+    }
+    logger.info("AI Gateway request", {
+      requestId,
+      tier: req.model,
+      stream: req.stream,
+      messageCount: req.messages.length,
+      hasTools: !!req.tools?.length,
+      tenantId: auth.namespaceId
+    });
+    try {
+      if (req.stream) {
+        return await handleStreamingRequest(reply, llm, req, requestId, logger);
+      }
+      return await handleCompletionRequest(reply, llm, req, requestId);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      logger.error("AI Gateway error", error, { requestId, tier: req.model });
+      return reply.code(500).send({
+        error: {
+          message: "Internal server error",
+          type: "server_error",
+          code: null,
+          param: null
+        }
+      });
+    }
+  });
+}
+async function handleCompletionRequest(reply, llm, req, requestId) {
+  const messages = toILLMMessages(req);
+  const startTime = Date.now();
+  const hasTools = req.tools && req.tools.length > 0;
+  if (hasTools && llm.chatWithTools) {
+    const tools = toILLMTools(req.tools);
+    const options = {
+      temperature: req.temperature,
+      maxTokens: req.max_tokens,
+      stop: normalizeStop(req.stop),
+      tools,
+      toolChoice: req.tool_choice
+    };
+    const result2 = await llm.chatWithTools(messages, options);
+    const toolCalls = result2.toolCalls?.map((tc) => ({
+      id: tc.id,
+      type: "function",
+      function: {
+        name: tc.name,
+        arguments: typeof tc.input === "string" ? tc.input : JSON.stringify(tc.input)
+      }
+    }));
+    const finishReason = result2.stopReason === "tool_use" ? "tool_calls" : result2.stopReason === "max_tokens" ? "length" : "stop";
+    const response2 = {
+      id: requestId,
+      object: "chat.completion",
+      created: Math.floor(startTime / 1e3),
+      model: req.model,
+      choices: [
+        {
+          index: 0,
+          message: {
+            role: "assistant",
+            content: result2.content || null,
+            ...toolCalls?.length ? { tool_calls: toolCalls } : {}
+          },
+          finish_reason: finishReason
+        }
+      ],
+      usage: {
+        prompt_tokens: result2.usage.promptTokens,
+        completion_tokens: result2.usage.completionTokens,
+        total_tokens: result2.usage.promptTokens + result2.usage.completionTokens
+      }
+    };
+    return reply.code(200).send(response2);
+  }
+  const systemPrompt = messages.find((m) => m.role === "system")?.content;
+  const userMessages = messages.filter((m) => m.role !== "system");
+  const prompt = userMessages.map((m) => m.content).join("\n\n");
+  const result = await llm.complete(prompt, {
+    systemPrompt,
+    temperature: req.temperature,
+    maxTokens: req.max_tokens,
+    stop: normalizeStop(req.stop)
+  });
+  const response = {
+    id: requestId,
+    object: "chat.completion",
+    created: Math.floor(startTime / 1e3),
+    model: req.model,
+    choices: [
+      {
+        index: 0,
+        message: { role: "assistant", content: result.content },
+        finish_reason: "stop"
+      }
+    ],
+    usage: {
+      prompt_tokens: result.usage.promptTokens,
+      completion_tokens: result.usage.completionTokens,
+      total_tokens: result.usage.promptTokens + result.usage.completionTokens
+    }
+  };
+  return reply.code(200).send(response);
+}
+async function handleStreamingRequest(reply, llm, req, requestId, logger) {
+  const created = Math.floor(Date.now() / 1e3);
+  reply.raw.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    "Connection": "keep-alive",
+    "X-Request-Id": requestId
+  });
+  reply.raw.flushHeaders();
+  const writeChunk = (chunk) => {
+    if (!reply.raw.writableEnded) {
+      reply.raw.write(`data: ${JSON.stringify(chunk)}
+
+`);
+    }
+  };
+  const writeDone = () => {
+    if (!reply.raw.writableEnded) {
+      reply.raw.write("data: [DONE]\n\n");
+      reply.raw.end();
+    }
+  };
+  try {
+    writeChunk({
+      id: requestId,
+      object: "chat.completion.chunk",
+      created,
+      model: req.model,
+      choices: [{ index: 0, delta: { role: "assistant" }, finish_reason: null }]
+    });
+    const systemPrompt = req.messages.find((m) => m.role === "system")?.content;
+    const userMessages = req.messages.filter((m) => m.role !== "system");
+    const prompt = userMessages.map((m) => m.content).join("\n\n");
+    for await (const text of llm.stream(prompt, {
+      systemPrompt,
+      temperature: req.temperature,
+      maxTokens: req.max_tokens,
+      stop: normalizeStop(req.stop)
+    })) {
+      writeChunk({
+        id: requestId,
+        object: "chat.completion.chunk",
+        created,
+        model: req.model,
+        choices: [{ index: 0, delta: { content: text }, finish_reason: null }]
+      });
+    }
+    writeChunk({
+      id: requestId,
+      object: "chat.completion.chunk",
+      created,
+      model: req.model,
+      choices: [{ index: 0, delta: {}, finish_reason: "stop" }]
+    });
+    writeDone();
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    logger.error("AI Gateway stream error", error, { requestId });
+    if (!reply.raw.writableEnded) {
+      reply.raw.write(
+        `data: ${JSON.stringify({ error: { message: error.message, type: "server_error" } })}
+
+`
+      );
+      reply.raw.end();
+    }
+  }
+  return reply;
+}
+function toILLMMessages(req) {
+  return req.messages.map((m) => {
+    const msg = { role: m.role, content: m.content };
+    if (m.tool_call_id) {
+      msg.toolCallId = m.tool_call_id;
+    }
+    if (m.tool_calls) {
+      msg.toolCalls = m.tool_calls.map((tc) => ({
+        id: tc.id,
+        name: tc.function.name,
+        input: safeJsonParse(tc.function.arguments)
+      }));
+    }
+    return msg;
+  });
+}
+function toILLMTools(tools) {
+  return tools.map((t) => ({
+    name: t.function.name,
+    description: t.function.description ?? "",
+    inputSchema: t.function.parameters ?? {}
+  }));
+}
+function normalizeStop(stop) {
+  if (!stop) {
+    return void 0;
+  }
+  return Array.isArray(stop) ? stop : [stop];
+}
+function safeJsonParse(str) {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return str;
+  }
+}
+function registerTelemetryRoutes(app, logger) {
+  app.post("/telemetry/v1/ingest", { schema: { tags: ["Telemetry"], summary: "Ingest telemetry events" } }, async (request, reply) => {
+    const auth = request.authContext;
+    if (!auth) {
+      return reply.code(401).send({ error: "Unauthorized" });
+    }
+    const parsed = TelemetryIngestRequestSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({
+        error: "Bad Request",
+        issues: parsed.error.issues
+      });
+    }
+    const analytics = platform.analytics;
+    if (!analytics) {
+      return reply.code(503).send({
+        error: "Analytics adapter not configured"
+      });
+    }
+    const { events } = parsed.data;
+    let accepted = 0;
+    let rejected = 0;
+    const errors = [];
+    for (let i = 0; i < events.length; i++) {
+      const event = events[i];
+      try {
+        await analytics.track(event.type, {
+          // Source attribution — who sent this event
+          _source: event.source,
+          _tenantId: auth.namespaceId,
+          _ts: event.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+          // Tags as flat properties for indexing
+          ...event.tags,
+          // Free-form payload
+          ...event.payload
+        });
+        accepted++;
+      } catch (err) {
+        rejected++;
+        const message = err instanceof Error ? err.message : String(err);
+        errors.push({ index: i, message });
+        logger.warn("Telemetry event rejected", {
+          index: i,
+          type: event.type,
+          source: event.source,
+          error: message
+        });
+      }
+    }
+    logger.info("Telemetry ingest", {
+      tenantId: auth.namespaceId,
+      accepted,
+      rejected,
+      totalEvents: events.length
+    });
+    const response = {
+      accepted,
+      rejected,
+      ...errors.length > 0 ? { errors } : {}
+    };
+    return reply.code(accepted > 0 ? 200 : 422).send(response);
+  });
+}
+var ALLOWED_METHODS = {
+  llm: /* @__PURE__ */ new Set(["complete", "stream", "chatWithTools"]),
+  cache: /* @__PURE__ */ new Set(["get", "set", "delete", "clear"]),
+  vectorStore: /* @__PURE__ */ new Set(["search", "upsert", "delete", "count"]),
+  analytics: /* @__PURE__ */ new Set(["track", "identify", "flush", "getEvents", "getStats", "getDailyStats"]),
+  embeddings: /* @__PURE__ */ new Set(["embed"]),
+  storage: /* @__PURE__ */ new Set(["read", "write", "delete", "list", "exists"]),
+  eventBus: /* @__PURE__ */ new Set(["publish", "subscribe"]),
+  sqlDatabase: /* @__PURE__ */ new Set(["query", "execute"]),
+  documentDatabase: /* @__PURE__ */ new Set(["find", "findOne", "insert", "update", "delete"])
+};
+function resolveAdapter(name) {
+  const adapterMap = {
+    llm: () => platform.llm,
+    cache: () => platform.cache,
+    analytics: () => platform.analytics,
+    vectorStore: () => platform.vectorStore,
+    embeddings: () => platform.embeddings,
+    storage: () => platform.storage,
+    eventBus: () => platform.eventBus,
+    sqlDatabase: () => platform.sqlDatabase,
+    documentDatabase: () => platform.documentDatabase
+  };
+  const getter = adapterMap[name];
+  return getter ? getter() : void 0;
+}
+function isAsyncIterable(value) {
+  return value !== null && typeof value === "object" && Symbol.asyncIterator in value;
+}
+function registerPlatformRoutes(app, logger) {
+  app.post(
+    "/platform/v1/:adapter/:method",
+    { schema: { tags: ["Platform"], summary: "Invoke a platform adapter method", hide: true } },
+    async (request, reply) => {
+      const auth = request.authContext;
+      if (!auth) {
+        return reply.code(401).send({ error: "Unauthorized" });
+      }
+      const { adapter: adapterName, method: methodName } = request.params;
+      const allowedMethods = ALLOWED_METHODS[adapterName];
+      if (!allowedMethods) {
+        return reply.code(404).send({
+          ok: false,
+          error: { message: `Unknown adapter: "${adapterName}"`, code: "ADAPTER_NOT_FOUND" },
+          durationMs: 0
+        });
+      }
+      if (!allowedMethods.has(methodName)) {
+        return reply.code(403).send({
+          ok: false,
+          error: { message: `Method "${methodName}" not allowed on adapter "${adapterName}"`, code: "METHOD_NOT_ALLOWED" },
+          durationMs: 0
+        });
+      }
+      const adapter = resolveAdapter(adapterName);
+      if (!adapter) {
+        return reply.code(503).send({
+          ok: false,
+          error: { message: `Adapter "${adapterName}" not configured`, code: "ADAPTER_UNAVAILABLE" },
+          durationMs: 0
+        });
+      }
+      const method = adapter[methodName];
+      if (typeof method !== "function") {
+        return reply.code(501).send({
+          ok: false,
+          error: { message: `Method "${methodName}" not implemented on adapter "${adapterName}"`, code: "METHOD_NOT_IMPLEMENTED" },
+          durationMs: 0
+        });
+      }
+      const parsed = PlatformCallRequestSchema.safeParse(request.body);
+      if (!parsed.success) {
+        return reply.code(400).send({
+          ok: false,
+          error: { message: "Invalid request body", code: "VALIDATION_ERROR" },
+          durationMs: 0
+        });
+      }
+      const { args } = parsed.data;
+      logger.info("Platform API call", {
+        adapter: adapterName,
+        method: methodName,
+        argCount: args.length,
+        tenantId: auth.namespaceId
+      });
+      const startTime = Date.now();
+      try {
+        const result = method.apply(adapter, args);
+        const resolved = result instanceof Promise ? await result : result;
+        if (isAsyncIterable(resolved)) {
+          reply.raw.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive"
+          });
+          reply.raw.flushHeaders();
+          for await (const chunk of resolved) {
+            if (!reply.raw.writableEnded) {
+              const data = typeof chunk === "string" ? chunk : JSON.stringify(chunk);
+              reply.raw.write(`data: ${data}
+
+`);
+            }
+          }
+          if (!reply.raw.writableEnded) {
+            reply.raw.write("data: [DONE]\n\n");
+            reply.raw.end();
+          }
+          return reply;
+        }
+        const durationMs = Date.now() - startTime;
+        return reply.code(200).send({
+          ok: true,
+          result: resolved,
+          durationMs
+        });
+      } catch (err) {
+        const durationMs = Date.now() - startTime;
+        const error = err instanceof Error ? err : new Error(String(err));
+        logger.error("Platform API error", error, {
+          adapter: adapterName,
+          method: methodName,
+          tenantId: auth.namespaceId
+        });
+        return reply.code(502).send({
+          ok: false,
+          error: { message: error.message, code: "ADAPTER_ERROR" },
+          durationMs
+        });
+      }
+    }
+  );
+}
+var MERGED_CACHE_KEY = "__gateway_merged_openapi";
+var MERGED_CACHE_TTL = 3e4;
+var UPSTREAM_SPEC_URLS = [
+  "http://localhost:5050/openapi.json",
+  "http://localhost:7778/openapi.json"
+];
+function registerAggregatedDocsRoutes(app, cache) {
+  app.get("/openapi-merged.json", async (_req, reply) => {
+    if (cache) {
+      try {
+        const hit = await cache.get(MERGED_CACHE_KEY);
+        if (hit) {
+          return reply.send(hit);
+        }
+      } catch {
+      }
+    }
+    const results = await Promise.allSettled(
+      UPSTREAM_SPEC_URLS.map(
+        (url) => fetch(url, { signal: AbortSignal.timeout(3e3) }).then((r) => r.json())
+      )
+    );
+    const specs = results.filter((r) => r.status === "fulfilled").map((r) => r.value);
+    const merged = mergeOpenAPISpecs(specs);
+    if (cache) {
+      try {
+        await cache.set(MERGED_CACHE_KEY, merged, MERGED_CACHE_TTL);
+      } catch {
+      }
+    }
+    return reply.send(merged);
+  });
+  app.register(async function docsAll(scope) {
+    const swaggerUi = await import('@fastify/swagger-ui');
+    await scope.register(swaggerUi.default ?? swaggerUi, {
+      routePrefix: "/docs-all",
+      uiConfig: {
+        url: "/openapi-merged.json",
+        docExpansion: "list",
+        deepLinking: true
+      }
+    });
+  });
+}
+var DEFAULT_RECONNECT_GRACE_MS = 1e4;
+var HostRegistry = class {
+  constructor(cache, store, options) {
+    this.cache = cache;
+    this.store = store;
+    this.reconnectGraceMs = options?.reconnectGraceMs ?? DEFAULT_RECONNECT_GRACE_MS;
+  }
+  graceTimers = /* @__PURE__ */ new Map();
+  reconnectGraceMs;
+  /**
+   * Restore hosts from persistent store into cache on startup.
+   * All restored hosts start as offline — live status comes from WS connections.
+   *
+   * Also resets any stale online/reconnecting hosts in cache to offline,
+   * since no WebSocket connections survive a Gateway restart.
+   */
+  async restore() {
+    await this.resetStaleHosts();
+    if (!this.store) {
+      return 0;
+    }
+    const hosts = await this.store.listAll();
+    for (const host of hosts) {
+      const offline = { ...host, status: "offline", connections: [] };
+      const cacheKey = this.hostKey(host.namespaceId, host.hostId);
+      await this.cache.set(cacheKey, offline);
+      await this.store.save(offline);
+      await this.addToIndex(host.namespaceId, host.hostId);
+    }
+    return hosts.length;
+  }
+  /**
+   * Reset all hosts in cache to offline.
+   * Called on startup — no WS connections exist yet, so nothing should be online.
+   * Uses namespace index maintained in cache to discover all namespaces.
+   */
+  async resetStaleHosts() {
+    const namespaces = await this.cache.get("host:namespaces") ?? ["default"];
+    for (const ns of namespaces) {
+      const hostIds = await this.cache.get(`host:index:${ns}`) ?? [];
+      for (const hostId of hostIds) {
+        const host = await this.cache.get(this.hostKey(ns, hostId));
+        if (host && (host.status === "online" || host.status === "reconnecting")) {
+          await this.cache.set(this.hostKey(ns, hostId), {
+            ...host,
+            status: "offline",
+            connections: []
+          });
+        }
+      }
+    }
+  }
+  async register(reg) {
+    const hostId = `host_${randomUUID().replace(/-/g, "").slice(0, 24)}`;
+    const machineToken = randomUUID();
+    const now = Date.now();
+    const descriptor = {
+      hostId,
+      name: reg.name,
+      namespaceId: reg.namespaceId,
+      capabilities: reg.capabilities,
+      status: "offline",
+      lastSeen: now,
+      connections: [],
+      hostType: reg.hostType,
+      createdAt: now,
+      updatedAt: now
+    };
+    if (this.store) {
+      await this.store.save(descriptor);
+      await this.store.saveToken(machineToken, hostId, reg.namespaceId);
+    }
+    await this.cache.set(this.hostKey(reg.namespaceId, hostId), descriptor);
+    await this.cache.set(this.tokenKey(machineToken), { hostId, namespaceId: reg.namespaceId });
+    await this.addToIndex(reg.namespaceId, hostId);
+    return { descriptor, machineToken };
+  }
+  async setOnline(hostId, namespaceId, connectionId) {
+    const host = await this.getFromCache(hostId, namespaceId);
+    if (!host) {
+      return;
+    }
+    const graceKey = `${namespaceId}:${hostId}`;
+    const graceTimer = this.graceTimers.get(graceKey);
+    if (graceTimer) {
+      clearTimeout(graceTimer);
+      this.graceTimers.delete(graceKey);
+    }
+    const updated = {
+      ...host,
+      status: "online",
+      lastSeen: Date.now(),
+      connections: [connectionId]
+    };
+    await this.cache.set(this.hostKey(namespaceId, hostId), updated);
+    if (this.store) {
+      await this.store.save(updated);
+    }
+  }
+  async setOffline(hostId, namespaceId, connectionId) {
+    const host = await this.getFromCache(hostId, namespaceId);
+    if (!host) {
+      return;
+    }
+    const connections = host.connections.filter((c) => c !== connectionId);
+    if (connections.length > 0) {
+      await this.cache.set(this.hostKey(namespaceId, hostId), {
+        ...host,
+        status: "online",
+        lastSeen: Date.now(),
+        connections
+      });
+      return;
+    }
+    const reconnecting = {
+      ...host,
+      status: "reconnecting",
+      lastSeen: Date.now(),
+      connections: []
+    };
+    await this.cache.set(this.hostKey(namespaceId, hostId), reconnecting);
+    if (this.store) {
+      await this.store.save(reconnecting);
+    }
+    const graceKey = `${namespaceId}:${hostId}`;
+    const existing = this.graceTimers.get(graceKey);
+    if (existing) {
+      clearTimeout(existing);
+    }
+    this.graceTimers.set(graceKey, setTimeout(async () => {
+      this.graceTimers.delete(graceKey);
+      const current = await this.getFromCache(hostId, namespaceId);
+      if (current?.status === "reconnecting") {
+        const offline = { ...current, status: "offline", lastSeen: Date.now() };
+        await this.cache.set(this.hostKey(namespaceId, hostId), offline);
+        if (this.store) {
+          await this.store.save(offline);
+        }
+      }
+    }, this.reconnectGraceMs));
+  }
+  async heartbeat(hostId, namespaceId) {
+    const host = await this.getFromCache(hostId, namespaceId);
+    if (!host) {
+      return;
+    }
+    await this.cache.set(this.hostKey(namespaceId, hostId), { ...host, lastSeen: Date.now() });
+  }
+  async get(hostId, namespaceId) {
+    const cached = await this.cache.get(this.hostKey(namespaceId, hostId));
+    if (cached) {
+      return cached;
+    }
+    if (!this.store) {
+      return null;
+    }
+    const stored = await this.store.get(hostId, namespaceId);
+    if (!stored) {
+      return null;
+    }
+    await this.cache.set(this.hostKey(namespaceId, hostId), { ...stored, status: "offline", connections: [] });
+    await this.addToIndex(namespaceId, hostId);
+    return { ...stored, status: "offline", connections: [] };
+  }
+  async resolveToken(token) {
+    const cached = await this.cache.get(this.tokenKey(token));
+    if (cached) {
+      return cached;
+    }
+    if (!this.store) {
+      return null;
+    }
+    const stored = await this.store.resolveToken(token);
+    if (!stored) {
+      return null;
+    }
+    await this.cache.set(this.tokenKey(token), stored);
+    return stored;
+  }
+  async list(namespaceId) {
+    if (this.store) {
+      const persisted = await this.store.list(namespaceId);
+      return Promise.all(
+        persisted.map(async (host) => {
+          const cached = await this.cache.get(this.hostKey(namespaceId, host.hostId));
+          return cached ?? { ...host, status: "offline", connections: [] };
+        })
+      );
+    }
+    const indexKey = `host:index:${namespaceId}`;
+    const hostIds = await this.cache.get(indexKey) ?? [];
+    const results = await Promise.all(
+      hostIds.map((id) => this.cache.get(this.hostKey(namespaceId, id)))
+    );
+    return results.filter((h) => h !== null);
+  }
+  async deregister(hostId, namespaceId) {
+    const deleted = this.store ? await this.store.delete(hostId, namespaceId) : false;
+    await this.cache.delete(this.hostKey(namespaceId, hostId));
+    await this.removeFromIndex(namespaceId, hostId);
+    return deleted;
+  }
+  async ensureRegistered(hostId, namespaceId, name, capabilities = []) {
+    const existing = await this.get(hostId, namespaceId);
+    if (existing) {
+      if (capabilities.length > 0 && JSON.stringify(existing.capabilities) !== JSON.stringify(capabilities)) {
+        const updated = { ...existing, capabilities, updatedAt: Date.now() };
+        if (this.store) {
+          await this.store.save(updated);
+        }
+        await this.cache.set(this.hostKey(namespaceId, hostId), updated);
+      }
+      return;
+    }
+    const now = Date.now();
+    const descriptor = {
+      hostId,
+      name,
+      namespaceId,
+      capabilities,
+      status: "offline",
+      lastSeen: now,
+      connections: [],
+      createdAt: now,
+      updatedAt: now
+    };
+    if (this.store) {
+      await this.store.save(descriptor);
+    }
+    await this.cache.set(this.hostKey(namespaceId, hostId), descriptor);
+    await this.addToIndex(namespaceId, hostId);
+  }
+  // ── Private helpers ──────────────────────────────────────────────
+  hostKey(namespaceId, hostId) {
+    return `host:registry:${namespaceId}:${hostId}`;
+  }
+  tokenKey(token) {
+    return `host:token:${token}`;
+  }
+  async getFromCache(hostId, namespaceId) {
+    return this.cache.get(this.hostKey(namespaceId, hostId));
+  }
+  async addToIndex(namespaceId, hostId) {
+    const indexKey = `host:index:${namespaceId}`;
+    const hostIds = await this.cache.get(indexKey) ?? [];
+    if (!hostIds.includes(hostId)) {
+      await this.cache.set(indexKey, [...hostIds, hostId]);
+    }
+    const nsKey = "host:namespaces";
+    const namespaces = await this.cache.get(nsKey) ?? [];
+    if (!namespaces.includes(namespaceId)) {
+      await this.cache.set(nsKey, [...namespaces, namespaceId]);
+    }
+  }
+  async removeFromIndex(namespaceId, hostId) {
+    const indexKey = `host:index:${namespaceId}`;
+    const hostIds = await this.cache.get(indexKey) ?? [];
+    await this.cache.set(indexKey, hostIds.filter((id) => id !== hostId));
+  }
+};
+var HELLO_TIMEOUT_MS = 5e3;
+var HEARTBEAT_INTERVAL_MS = 3e4;
+var HEARTBEAT_GRACE_MS = 1e4;
+function send(ws, msg) {
+  ws.send(JSON.stringify(msg));
+}
+function createWsHandler(cache, jwtConfig, logger, hostRegistry) {
+  const registry = hostRegistry ?? new HostRegistry(cache);
+  const buffer = new AdaptiveBuffer(cache);
+  return async function wsHandler(socket, request) {
+    const token = extractBearerToken(request.headers.authorization);
+    if (!token) {
+      logDiagnosticEvent(logger, {
+        domain: "service",
+        event: "gateway.hosts.ws.auth",
+        level: "warn",
+        reasonCode: "websocket_auth_failed",
+        message: "Host WebSocket connection missing authorization token",
+        outcome: "failed",
+        serviceId: "gateway",
+        route: "/hosts/connect"
+      });
+      socket.close(1008, "Missing Authorization header");
+      return;
+    }
+    const tokenEntry = await resolveToken(token, cache, jwtConfig);
+    if (!tokenEntry || tokenEntry.type !== "machine") {
+      logDiagnosticEvent(logger, {
+        domain: "service",
+        event: "gateway.hosts.ws.auth",
+        level: "warn",
+        reasonCode: "websocket_auth_failed",
+        message: "Host WebSocket machine token rejected",
+        outcome: "failed",
+        serviceId: "gateway",
+        route: "/hosts/connect"
+      });
+      socket.close(1008, "Invalid machine token");
+      return;
+    }
+    const { userId: hostId, namespaceId } = tokenEntry;
+    const connectionId = randomUUID();
+    const sessionId = randomUUID();
+    let protocolVersion = null;
+    let helloCaps = [];
+    let helloDone = false;
+    const protocolVersions = SUPPORTED_PROTOCOL_VERSIONS;
+    await new Promise((resolve, reject) => {
+      const helloTimeout = setTimeout(() => {
+        if (!helloDone) {
+          helloDone = true;
+          logDiagnosticEvent(logger, {
+            domain: "service",
+            event: "gateway.hosts.ws.handshake",
+            level: "warn",
+            reasonCode: "websocket_hello_timeout",
+            message: "Host WebSocket hello timed out",
+            outcome: "failed",
+            serviceId: "gateway",
+            route: "/hosts/connect",
+            evidence: {
+              hostId,
+              namespaceId
+            }
+          });
+          socket.close(1008, "Hello timeout");
+          reject(new Error("Hello timeout"));
+        }
+      }, HELLO_TIMEOUT_MS);
+      socket.once("message", (raw) => {
+        if (helloDone) {
+          return;
+        }
+        helloDone = true;
+        clearTimeout(helloTimeout);
+        try {
+          const msg = HelloMessageSchema.parse(JSON.parse(raw.toString()));
+          if (!protocolVersions.includes(msg.protocolVersion)) {
+            logDiagnosticEvent(logger, {
+              domain: "service",
+              event: "gateway.hosts.ws.handshake",
+              level: "warn",
+              reasonCode: "websocket_protocol_unsupported",
+              message: "Host WebSocket protocol version is unsupported",
+              outcome: "failed",
+              serviceId: "gateway",
+              route: "/hosts/connect",
+              evidence: {
+                hostId,
+                namespaceId,
+                protocolVersion: msg.protocolVersion,
+                supportedVersions: [...SUPPORTED_PROTOCOL_VERSIONS]
+              }
+            });
+            send(socket, {
+              type: "negotiate",
+              supportedVersions: [...SUPPORTED_PROTOCOL_VERSIONS]
+            });
+            socket.close(1008, "Unsupported protocol version");
+            reject(new Error("Unsupported protocol version"));
+            return;
+          }
+          protocolVersion = msg.protocolVersion;
+          helloCaps = msg.capabilities ?? [];
+          resolve();
+        } catch (error) {
+          logDiagnosticEvent(logger, {
+            domain: "service",
+            event: "gateway.hosts.ws.handshake",
+            level: "warn",
+            reasonCode: "websocket_handshake_invalid",
+            message: "Host WebSocket hello message is invalid",
+            outcome: "failed",
+            error: error instanceof Error ? error : new Error(String(error)),
+            serviceId: "gateway",
+            route: "/hosts/connect",
+            evidence: {
+              hostId,
+              namespaceId
+            }
+          });
+          socket.close(1008, "Invalid hello message");
+          reject(new Error("Invalid hello"));
+        }
+      });
+    }).catch(() => {
+    });
+    if (!protocolVersion) {
+      return;
+    }
+    const clientRecord = await getClientByHostId(cache, hostId);
+    const registryCaps = (clientRecord?.capabilities ?? []).map((c) => HostCapabilitySchema.safeParse(c)).filter((r) => r.success).map((r) => r.data);
+    const validatedHelloCaps = clientRecord ? [] : helloCaps.map((c) => HostCapabilitySchema.safeParse(c)).filter((r) => r.success).map((r) => r.data);
+    const capabilities = clientRecord ? registryCaps : validatedHelloCaps;
+    await registry.ensureRegistered(hostId, namespaceId, clientRecord?.name ?? hostId, capabilities);
+    await registry.setOnline(hostId, namespaceId, connectionId);
+    globalDispatcher.registerConnection(hostId, namespaceId, socket, capabilities);
+    send(socket, {
+      type: "connected",
+      protocolVersion,
+      hostId,
+      sessionId
+    });
+    const buffered = await buffer.flush(hostId);
+    for (const call of buffered) {
+      send(socket, {
+        type: "call",
+        requestId: call.requestId,
+        adapter: call.adapter,
+        method: call.method,
+        args: call.args,
+        trace: { traceId: call.requestId, spanId: randomUUID() }
+      });
+    }
+    let lastHeartbeat = Date.now();
+    const heartbeatWatchdog = setInterval(async () => {
+      const elapsed = Date.now() - lastHeartbeat;
+      if (elapsed > HEARTBEAT_INTERVAL_MS + HEARTBEAT_GRACE_MS) {
+        const host = await registry.get(hostId, namespaceId);
+        if (host && host.status !== "degraded") {
+          await cache.set(`host:registry:${namespaceId}:${hostId}`, {
+            ...host,
+            status: "degraded"
+          });
+        }
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+    socket.on("message", async (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        switch (msg.type) {
+          case "heartbeat":
+            lastHeartbeat = Date.now();
+            await registry.heartbeat(hostId, namespaceId);
+            send(socket, { type: "ack" });
+            break;
+          case "chunk":
+          case "result":
+          case "error":
+            globalDispatcher.handleInbound(msg);
+            break;
+          case "adapter:call":
+            void handleAdapterCall(msg, socket, hostId, namespaceId);
+            break;
+        }
+      } catch (error) {
+        logDiagnosticEvent(logger, {
+          domain: "service",
+          event: "gateway.hosts.ws.message",
+          level: "warn",
+          reasonCode: "websocket_message_invalid",
+          message: "Host WebSocket message is malformed",
+          outcome: "failed",
+          error: error instanceof Error ? error : new Error(String(error)),
+          serviceId: "gateway",
+          route: "/hosts/connect",
+          evidence: {
+            hostId,
+            namespaceId
+          }
+        });
+      }
+    });
+    socket.on("close", async () => {
+      clearInterval(heartbeatWatchdog);
+      globalDispatcher.removeConnection(hostId, namespaceId);
+      const cancelled = executionRegistry.cancelByHost(hostId, "disconnect");
+      if (cancelled.length > 0) {
+        logDiagnosticEvent(logger, {
+          domain: "service",
+          event: "gateway.hosts.ws.disconnect",
+          level: "warn",
+          reasonCode: "execution_dispatch_failed",
+          message: "Host disconnected and active executions were cancelled",
+          outcome: "failed",
+          serviceId: "gateway",
+          route: "/hosts/connect",
+          evidence: {
+            hostId,
+            namespaceId,
+            cancelledExecutions: cancelled.length
+          }
+        });
+      }
+      await registry.setOffline(hostId, namespaceId, connectionId);
+    });
+  };
+  async function handleAdapterCall(msg, socket, hostId, namespaceId) {
+    const requestId = msg["requestId"];
+    const parsed = AdapterCallMessageSchema.safeParse(msg);
+    if (!parsed.success) {
+      logDiagnosticEvent(logger, {
+        domain: "service",
+        event: "gateway.hosts.adapter-call",
+        level: "warn",
+        reasonCode: "websocket_message_invalid",
+        message: "Host adapter call message is invalid",
+        outcome: "failed",
+        serviceId: "gateway",
+        route: "/hosts/connect",
+        evidence: {
+          hostId,
+          namespaceId,
+          requestId
+        }
+      });
+      send(socket, {
+        type: "adapter:error",
+        requestId: requestId ?? "unknown",
+        error: { code: "INVALID_MESSAGE", message: parsed.error.message, retryable: false }
+      });
+      return;
+    }
+    const call = parsed.data;
+    const adapterCheck = AdapterNameSchema.safeParse(call.adapter);
+    if (!adapterCheck.success) {
+      logDiagnosticEvent(logger, {
+        domain: "service",
+        event: "gateway.hosts.adapter-call",
+        level: "warn",
+        reasonCode: "adapter_call_rejected",
+        message: "Host adapter call rejected by gateway allowlist",
+        outcome: "failed",
+        serviceId: "gateway",
+        route: "/hosts/connect",
+        evidence: {
+          hostId,
+          namespaceId,
+          requestId: call.requestId,
+          adapter: call.adapter,
+          method: call.method
+        }
+      });
+      send(socket, {
+        type: "adapter:error",
+        requestId: call.requestId,
+        error: { code: "ADAPTER_CALL_REJECTED", message: `Adapter not allowed: ${call.adapter}`, retryable: false }
+      });
+      return;
+    }
+    const restApiUrl = process.env.REST_API_URL ?? "http://localhost:5050";
+    const internalSecret = process.env.GATEWAY_INTERNAL_SECRET ?? "";
+    try {
+      const response = await fetch(`${restApiUrl}/api/v1/internal/adapter-call`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-internal-secret": internalSecret
+        },
+        body: JSON.stringify({
+          requestId: call.requestId,
+          adapter: call.adapter,
+          method: call.method,
+          args: call.args,
+          context: {
+            ...call.context,
+            namespaceId,
+            hostId
+          }
+        })
+      });
+      const body = await response.json();
+      if (body.ok) {
+        send(socket, {
+          type: "adapter:response",
+          requestId: call.requestId,
+          result: body.result
+        });
+      } else {
+        send(socket, {
+          type: "adapter:error",
+          requestId: call.requestId,
+          error: body.error ?? { code: "ADAPTER_ERROR", message: "Unknown error", retryable: false }
+        });
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logDiagnosticEvent(logger, {
+        domain: "service",
+        event: "gateway.hosts.adapter-call",
+        level: "error",
+        reasonCode: "adapter_bridge_unavailable",
+        message: "Gateway could not reach REST adapter bridge",
+        outcome: "failed",
+        error: err instanceof Error ? err : new Error(String(err)),
+        serviceId: "gateway",
+        route: "/hosts/connect",
+        evidence: {
+          hostId,
+          namespaceId,
+          requestId: call.requestId,
+          adapter: call.adapter,
+          method: call.method,
+          restApiUrl
+        }
+      });
+      send(socket, {
+        type: "adapter:error",
+        requestId: call.requestId,
+        error: { code: "ADAPTER_CALL_TIMEOUT", message: `REST API unreachable: ${message}`, retryable: true }
+      });
+    }
+  }
+}
+var HELLO_TIMEOUT_MS2 = 5e3;
+function send2(ws, msg) {
+  if (ws.readyState === ws.OPEN) {
+    ws.send(JSON.stringify(msg));
+  }
+}
+function createClientWsHandler(cache, jwtConfig, logger) {
+  return async function clientWsHandler(socket, request) {
+    const queryToken = new URL(request.url ?? "/", "http://localhost").searchParams.get("access_token");
+    const token = extractBearerToken(request.headers.authorization) ?? queryToken ?? null;
+    if (!token) {
+      socket.close(1008, "Missing Authorization");
+      return;
+    }
+    const authContext = await resolveToken(token, cache, jwtConfig);
+    if (!authContext) {
+      socket.close(1008, "Invalid token");
+      return;
+    }
+    const connectionId = randomUUID();
+    let helloDone = false;
+    await new Promise((resolve, reject) => {
+      const helloTimeout = setTimeout(() => {
+        if (!helloDone) {
+          helloDone = true;
+          socket.close(1008, "Hello timeout");
+          reject(new Error("Hello timeout"));
+        }
+      }, HELLO_TIMEOUT_MS2);
+      socket.once("message", (raw) => {
+        if (helloDone) {
+          return;
+        }
+        helloDone = true;
+        clearTimeout(helloTimeout);
+        try {
+          const msg = ClientHelloSchema.parse(JSON.parse(raw.toString()));
+          void msg;
+          resolve();
+        } catch {
+          socket.close(1008, "Invalid hello message");
+          reject(new Error("Invalid client:hello"));
+        }
+      });
+    }).catch(() => {
+    });
+    if (!helloDone || socket.readyState !== socket.OPEN) {
+      return;
+    }
+    subscriptionRegistry.registerSocket(connectionId, socket);
+    send2(socket, {
+      type: "client:connected",
+      protocolVersion: CLIENT_PROTOCOL_VERSION,
+      connectionId
+    });
+    logger.debug("Client connected", { connectionId, namespaceId: authContext.namespaceId });
+    socket.on("message", (raw) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(raw.toString());
+      } catch {
+        send2(socket, {
+          type: "client:error",
+          code: "INVALID_MESSAGE",
+          message: "Malformed JSON"
+        });
+        return;
+      }
+      switch (parsed.type) {
+        case "client:subscribe": {
+          const result = ClientSubscribeSchema.safeParse(parsed);
+          if (!result.success) {
+            send2(socket, { type: "client:error", code: "INVALID_MESSAGE", message: "Invalid subscribe message" });
+            return;
+          }
+          const { executionId } = result.data;
+          const execution = executionRegistry.get(executionId);
+          if (!execution) {
+            send2(socket, { type: "client:error", code: "EXECUTION_NOT_FOUND", message: `Execution ${executionId} not found`, executionId });
+            return;
+          }
+          if (execution.namespaceId !== authContext.namespaceId) {
+            send2(socket, { type: "client:error", code: "FORBIDDEN", message: "Execution belongs to another namespace", executionId });
+            return;
+          }
+          subscriptionRegistry.subscribe(connectionId, executionId);
+          break;
+        }
+        case "client:unsubscribe": {
+          const result = ClientUnsubscribeSchema.safeParse(parsed);
+          if (!result.success) {
+            send2(socket, { type: "client:error", code: "INVALID_MESSAGE", message: "Invalid unsubscribe message" });
+            return;
+          }
+          subscriptionRegistry.unsubscribe(connectionId, result.data.executionId);
+          break;
+        }
+        case "client:cancel": {
+          const result = ClientCancelSchema.safeParse(parsed);
+          if (!result.success) {
+            send2(socket, { type: "client:error", code: "INVALID_MESSAGE", message: "Invalid cancel message" });
+            return;
+          }
+          const { executionId, reason } = result.data;
+          const execution = executionRegistry.get(executionId);
+          if (!execution) {
+            send2(socket, { type: "client:error", code: "EXECUTION_NOT_FOUND", message: `Execution ${executionId} not found`, executionId });
+            return;
+          }
+          if (execution.namespaceId !== authContext.namespaceId) {
+            send2(socket, { type: "client:error", code: "FORBIDDEN", message: "Execution belongs to another namespace", executionId });
+            return;
+          }
+          const cancelled = executionRegistry.cancel(executionId, reason ?? "user");
+          if (!cancelled) {
+            send2(socket, { type: "client:error", code: "CANCEL_FAILED", message: "Execution already completed or cancelled", executionId });
+          }
+          break;
+        }
+        default:
+          send2(socket, { type: "client:error", code: "INVALID_MESSAGE", message: `Unknown message type: ${String(parsed.type)}` });
+      }
+    });
+    socket.on("close", () => {
+      subscriptionRegistry.removeConnection(connectionId);
+      logger.debug("Client disconnected", { connectionId });
+    });
+  };
+}
+
+// src/ws/gateway-ws.ts
+var GATEWAY_WS_PATHS = /* @__PURE__ */ new Set(["/hosts/connect", "/clients/connect"]);
+function attachGatewayWs(server, cache, jwtConfig, logger, hostRegistry) {
+  const wss = new WebSocketServer({ noServer: true });
+  const hostsHandler = createWsHandler(cache, jwtConfig, logger, hostRegistry);
+  const clientsHandler = createClientWsHandler(cache, jwtConfig, logger);
+  const existingListeners = server.listeners("upgrade").slice();
+  server.removeAllListeners("upgrade");
+  server.on("upgrade", (req, socket, head) => {
+    const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    if (GATEWAY_WS_PATHS.has(pathname)) {
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        if (pathname === "/hosts/connect") {
+          hostsHandler(ws, req);
+        } else {
+          clientsHandler(ws, req);
+        }
+      });
+    } else {
+      for (const listener of existingListeners) {
+        listener.call(server, req, socket, head);
+      }
+    }
+  });
+  logger.info("Gateway WS endpoints attached", { paths: [...GATEWAY_WS_PATHS] });
+}
+function normalizeRoute(route) {
+  if (!route) {
+    return "unknown";
+  }
+  return route.split("?")[0].replace(/\/[0-9a-fA-F-]{6,}/g, "/:id");
+}
+function metricLine(name, value, labels) {
+  if (!labels || Object.keys(labels).length === 0) {
+    return `${name} ${value}`;
+  }
+  const pairs = Object.entries(labels).map(([key, labelValue]) => `${key}="${labelValue.replace(/"/g, '\\"')}"`);
+  return `${name}{${pairs.join(",")}} ${value}`;
+}
+var GatewayObservabilityCollector = class {
+  constructor(config) {
+    this.config = config;
+    this.dependencies = Object.keys(this.config.upstreams).map((serviceId) => ({
+      serviceId,
+      required: false,
+      description: "Gateway upstream"
+    }));
+  }
+  instanceId = `${hostname()}:${process.pid}`;
+  eventLoop = monitorEventLoopDelay({ resolution: 20 });
+  routeStats = /* @__PURE__ */ new Map();
+  operationMetrics = new OperationMetricsTracker();
+  startedAt = Date.now();
+  dependencies;
+  lastCpuUsage = process.cpuUsage();
+  lastCpuTime = Date.now();
+  intervalId = null;
+  activeOperations = 0;
+  requestsTotal = 0;
+  errorsTotal = 0;
+  lastSnapshot = {
+    cpuPercent: 0,
+    rssBytes: process.memoryUsage().rss,
+    heapUsedBytes: process.memoryUsage().heapUsed,
+    eventLoopLagMs: 0
+  };
+  register(server) {
+    const hookServer = server;
+    this.eventLoop.enable();
+    this.intervalId = setInterval(() => this.captureRuntimeSnapshot(), 1e4);
+    this.captureRuntimeSnapshot();
+    hookServer.addHook("onRequest", (request, _reply, done) => {
+      request.kbMetricsStart = performance.now();
+      this.activeOperations += 1;
+      done();
+    });
+    hookServer.addHook("onResponse", (request, reply, done) => {
+      const started = request.kbMetricsStart ?? performance.now();
+      const durationMs = Math.max(performance.now() - started, 0);
+      const route = `${request.method.toUpperCase()} ${normalizeRoute(request.routeOptions?.url ?? request.url)}`;
+      const stats = this.routeStats.get(route) ?? {
+        count: 0,
+        totalDurationMs: 0,
+        maxDurationMs: 0,
+        errorCount: 0
+      };
+      stats.count += 1;
+      stats.totalDurationMs += durationMs;
+      stats.maxDurationMs = Math.max(stats.maxDurationMs, durationMs);
+      if (reply.statusCode >= 400) {
+        stats.errorCount += 1;
+        this.errorsTotal += 1;
+      }
+      this.routeStats.set(route, stats);
+      this.requestsTotal += 1;
+      this.activeOperations = Math.max(0, this.activeOperations - 1);
+      done();
+    });
+    hookServer.addHook("onClose", (_instance, done) => {
+      if (this.intervalId) {
+        clearInterval(this.intervalId);
+        this.intervalId = null;
+      }
+      this.eventLoop.disable();
+      done();
+    });
+  }
+  buildDescribe() {
+    return createServiceObservabilityDescribe({
+      schema: OBSERVABILITY_SCHEMA,
+      contractVersion: OBSERVABILITY_CONTRACT_VERSION,
+      serviceId: "gateway",
+      instanceId: this.instanceId,
+      serviceType: "gateway",
+      version: "1.0.0",
+      environment: process.env.NODE_ENV ?? "development",
+      startedAt: new Date(this.startedAt).toISOString(),
+      dependencies: this.dependencies,
+      metricsEndpoint: "/metrics",
+      healthEndpoint: "/observability/health",
+      logsSource: "gateway",
+      capabilities: ["httpMetrics", "eventLoopMetrics", "operationMetrics", "logCorrelation"],
+      metricFamilies: [...CANONICAL_OBSERVABILITY_METRICS]
+    });
+  }
+  buildHealth(input) {
+    const checks = [
+      ...input.adapterChecks.map((entry) => ({
+        id: `adapter:${entry.id}`,
+        status: entry.available ? "ok" : "warn",
+        latencyMs: entry.latencyMs,
+        message: entry.available ? "Adapter available" : "Adapter unavailable"
+      })),
+      ...input.upstreamChecks.map((entry) => ({
+        id: `upstream:${entry.id}`,
+        status: entry.status === "up" ? "ok" : "warn",
+        latencyMs: entry.latencyMs,
+        message: entry.status === "up" ? "Upstream healthy" : "Upstream unavailable"
+      }))
+    ];
+    const topOperations = mergeTopOperations(
+      Array.from(this.routeStats.entries()).sort((a, b) => b[1].count - a[1].count || b[1].maxDurationMs - a[1].maxDurationMs).slice(0, 5).map(([operation, stats]) => ({
+        operation: `http.${operation}`,
+        count: stats.count,
+        avgDurationMs: stats.count > 0 ? stats.totalDurationMs / stats.count : 0,
+        maxDurationMs: stats.maxDurationMs,
+        errorCount: stats.errorCount
+      })),
+      this.operationMetrics.getTopOperations()
+    );
+    return createServiceObservabilityHealth({
+      schema: OBSERVABILITY_SCHEMA,
+      contractVersion: OBSERVABILITY_CONTRACT_VERSION,
+      serviceId: "gateway",
+      instanceId: this.instanceId,
+      observedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      status: input.status,
+      uptimeSec: Math.floor((Date.now() - this.startedAt) / 1e3),
+      metricsEndpoint: "/metrics",
+      logsSource: "gateway",
+      capabilities: ["httpMetrics", "eventLoopMetrics", "operationMetrics", "logCorrelation"],
+      checks,
+      snapshot: {
+        cpuPercent: this.lastSnapshot.cpuPercent,
+        rssBytes: this.lastSnapshot.rssBytes,
+        heapUsedBytes: this.lastSnapshot.heapUsedBytes,
+        eventLoopLagMs: this.lastSnapshot.eventLoopLagMs,
+        activeOperations: this.activeOperations
+      },
+      topOperations,
+      state: input.status === "healthy" ? "active" : input.status === "degraded" ? "partial_observability" : "insufficient_data",
+      meta: {
+        requestsTotal: this.requestsTotal,
+        errorsTotal: this.errorsTotal
+      }
+    });
+  }
+  async renderPrometheusMetrics(healthStatus) {
+    this.captureRuntimeSnapshot();
+    const lines = [
+      "# HELP process_cpu_percent Current process CPU usage percentage",
+      "# TYPE process_cpu_percent gauge",
+      metricLine("process_cpu_percent", this.lastSnapshot.cpuPercent),
+      "# HELP process_rss_bytes Current process resident set size in bytes",
+      "# TYPE process_rss_bytes gauge",
+      metricLine("process_rss_bytes", this.lastSnapshot.rssBytes),
+      "# HELP process_heap_used_bytes Current process heap used in bytes",
+      "# TYPE process_heap_used_bytes gauge",
+      metricLine("process_heap_used_bytes", this.lastSnapshot.heapUsedBytes),
+      "# HELP process_event_loop_lag_ms Current event loop lag in milliseconds",
+      "# TYPE process_event_loop_lag_ms gauge",
+      metricLine("process_event_loop_lag_ms", this.lastSnapshot.eventLoopLagMs),
+      "# HELP service_health_status Service health status (2=healthy, 1=degraded, 0=unhealthy)",
+      "# TYPE service_health_status gauge",
+      metricLine("service_health_status", healthStatus === "healthy" ? 2 : healthStatus === "degraded" ? 1 : 0),
+      "# HELP service_restarts_total Service restart counter within current process lifetime",
+      "# TYPE service_restarts_total gauge",
+      metricLine("service_restarts_total", 0),
+      "# HELP service_active_operations Current number of active operations",
+      "# TYPE service_active_operations gauge",
+      metricLine("service_active_operations", this.activeOperations),
+      "# HELP http_requests_total Total number of HTTP requests",
+      "# TYPE http_requests_total counter",
+      "# HELP http_errors_total Total number of HTTP errors (4xx, 5xx)",
+      "# TYPE http_errors_total counter",
+      "# HELP http_request_duration_ms Total duration of HTTP requests grouped by route",
+      "# TYPE http_request_duration_ms summary",
+      "# HELP service_operation_total Total number of service operations",
+      "# TYPE service_operation_total counter",
+      "# HELP service_operation_duration_ms Total duration of service operations grouped by route",
+      "# TYPE service_operation_duration_ms summary"
+    ];
+    for (const [route, stats] of this.routeStats.entries()) {
+      const status = stats.errorCount > 0 ? "error" : "ok";
+      lines.push(metricLine("http_requests_total", stats.count, { route }));
+      lines.push(metricLine("http_errors_total", stats.errorCount, { route }));
+      lines.push(metricLine("http_request_duration_ms", Number(stats.totalDurationMs.toFixed(2)), { route }));
+      lines.push(metricLine("service_operation_total", stats.count, { operation: `http.${route}`, status }));
+      lines.push(metricLine("service_operation_duration_ms", Number(stats.totalDurationMs.toFixed(2)), { operation: `http.${route}`, status }));
+    }
+    lines.push(...this.operationMetrics.getMetricLines());
+    return `${lines.join("\n")}
+`;
+  }
+  recordOperation(operation, durationMs = 0, status = "ok") {
+    this.operationMetrics.recordOperation(operation, durationMs, status);
+  }
+  observeOperation(operation, work) {
+    return this.operationMetrics.observeOperation(operation, work);
+  }
+  captureRuntimeSnapshot() {
+    const currentUsage = process.cpuUsage(this.lastCpuUsage);
+    const currentTime = Date.now();
+    const deltaTime = Math.max(currentTime - this.lastCpuTime, 1);
+    this.lastCpuUsage = process.cpuUsage();
+    this.lastCpuTime = currentTime;
+    const cpuTimeMs = (currentUsage.user + currentUsage.system) / 1e3;
+    const memory = process.memoryUsage();
+    const eventLoopLagMs = Number((this.eventLoop.mean / 1e6).toFixed(2));
+    this.lastSnapshot = {
+      cpuPercent: Number(Math.min(cpuTimeMs / deltaTime * 100, 100).toFixed(2)),
+      rssBytes: memory.rss,
+      heapUsedBytes: memory.heapUsed,
+      eventLoopLagMs: Number.isFinite(eventLoopLagMs) ? eventLoopLagMs : 0
+    };
+    this.eventLoop.reset();
+  }
+};
+function mergeTopOperations(httpOperations, domainOperations, limit = 5) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const item of [...httpOperations, ...domainOperations]) {
+    const existing = merged.get(item.operation);
+    if (!existing) {
+      merged.set(item.operation, { ...item });
+      continue;
+    }
+    const count = (existing.count ?? 0) + (item.count ?? 0);
+    const totalDurationMs = (existing.avgDurationMs ?? 0) * (existing.count ?? 0) + (item.avgDurationMs ?? 0) * (item.count ?? 0);
+    merged.set(item.operation, {
+      operation: item.operation,
+      count,
+      avgDurationMs: count > 0 ? totalDurationMs / count : 0,
+      maxDurationMs: Math.max(existing.maxDurationMs ?? 0, item.maxDurationMs ?? 0),
+      errorCount: (existing.errorCount ?? 0) + (item.errorCount ?? 0)
+    });
+  }
+  const ranked = Array.from(merged.values()).sort((a, b) => (b.count ?? 0) - (a.count ?? 0) || (b.maxDurationMs ?? 0) - (a.maxDurationMs ?? 0));
+  const sliced = ranked.slice(0, limit);
+  if (domainOperations.length === 0 || sliced.some((item) => !item.operation.startsWith("http."))) {
+    return sliced;
+  }
+  const firstDomainOperation = ranked.find((item) => !item.operation.startsWith("http."));
+  if (!firstDomainOperation) {
+    return sliced;
+  }
+  return [...sliced.slice(0, Math.max(0, limit - 1)), firstDomainOperation];
+}
+async function createServer(config, cache, logger, jwtConfig, registry) {
+  const gatewayLogger = createCorrelatedLogger(logger, {
+    serviceId: "gateway",
+    logsSource: "gateway",
+    layer: "gateway",
+    service: "server",
+    operation: "gateway.http"
+  });
+  const app = Fastify({
+    logger: false
+  });
+  const isProduction = process.env.NODE_ENV === "production";
+  await registerOpenAPI(app, {
+    title: "KB Labs Gateway",
+    description: "Central API gateway \u2014 auth, LLM, telemetry, platform dispatch",
+    version: "1.0.0",
+    servers: [{ url: "http://localhost:4000", description: "Local dev" }],
+    ui: !isProduction
+  });
+  await app.register(fastifyCors, { origin: true });
+  const observability = new GatewayObservabilityCollector(config);
+  observability.register(app);
+  app.addHook("onRequest", async (request, reply) => {
+    const requestId = request.headers["x-request-id"] || request.id || randomUUID();
+    const traceId = request.headers["x-trace-id"] || randomUUID();
+    request.id = requestId;
+    reply.header("X-Request-Id", requestId);
+    reply.header("X-Trace-Id", traceId);
+    request.kbLogger = createCorrelatedLogger(logger, {
+      serviceId: "gateway",
+      logsSource: "gateway",
+      layer: "gateway",
+      service: "request",
+      requestId,
+      traceId,
+      method: request.method,
+      url: request.url,
+      operation: "http.request"
+    });
+    request.kbLogger.info(`\u2192 ${request.method.toUpperCase()} ${request.url}`);
+  });
+  app.addHook("onResponse", async (request, reply) => {
+    const requestLogger = request.kbLogger;
+    if (!requestLogger) {
+      return;
+    }
+    requestLogger.info(`\u2713 ${request.method.toUpperCase()} ${request.url} ${reply.statusCode}`, {
+      statusCode: reply.statusCode
+    });
+  });
+  const PROXY_TIMEOUT_MS = 36e5;
+  for (const [name, upstream] of Object.entries(config.upstreams)) {
+    await app.register(fastifyHttpProxy, {
+      upstream: upstream.url,
+      prefix: upstream.prefix,
+      rewritePrefix: upstream.rewritePrefix ?? upstream.prefix,
+      disableCache: true,
+      websocket: upstream.websocket ?? false,
+      http: {
+        requestOptions: {
+          timeout: PROXY_TIMEOUT_MS
+        }
+      }
+    });
+    gatewayLogger.info(`Upstream registered: ${name} \u2192 ${upstream.url} (${upstream.prefix}${upstream.websocket ? ", ws" : ""})`);
+  }
+  await app.register(async function gatewayRoutes(scope) {
+    scope.addHook("onRequest", createAuthMiddleware(cache, jwtConfig));
+    const authService = new AuthService(cache, jwtConfig);
+    registerAuthRoutes(scope, authService);
+    const HEALTH_CACHE_KEY = "__gateway_health";
+    const HEALTH_CACHE_TTL = 15e3;
+    const startupTime = Date.now();
+    const collectHealthSnapshot = async () => {
+      const cached = await cache.get(HEALTH_CACHE_KEY).catch(() => null);
+      if (cached) {
+        return cached;
+      }
+      const adapterNames = ["llm", "cache", "analytics", "vectorStore", "embeddings"];
+      const adapters = {};
+      for (const name of adapterNames) {
+        await observability.observeOperation(`gateway.adapter.${name}`, async () => {
+          const probeStart = Date.now();
+          try {
+            const adapter = platform[name];
+            adapters[name] = { available: !!adapter, latencyMs: Date.now() - probeStart };
+          } catch {
+            adapters[name] = { available: false, latencyMs: Date.now() - probeStart };
+          }
+        });
+      }
+      const upstreams = {};
+      for (const [name, upstream] of Object.entries(config.upstreams)) {
+        await observability.observeOperation(`gateway.upstream.${name}.health`, async () => {
+          const probeStart = Date.now();
+          try {
+            const res = await fetch(`${upstream.url}/health`, {
+              signal: AbortSignal.timeout(2e3)
+            });
+            const latencyMs = Date.now() - probeStart;
+            upstreams[name] = { status: res.ok ? "up" : "down", latencyMs };
+            if (!res.ok) {
+              logDiagnosticEvent(logger, {
+                domain: "service",
+                event: "gateway.upstream.health",
+                level: "warn",
+                reasonCode: "upstream_unavailable",
+                message: "Gateway upstream health probe failed",
+                outcome: "failed",
+                serviceId: "gateway",
+                route: `${upstream.prefix}/health`,
+                evidence: {
+                  upstreamId: name,
+                  upstreamUrl: upstream.url,
+                  statusCode: res.status,
+                  latencyMs
+                }
+              });
+            }
+          } catch (error) {
+            const latencyMs = Date.now() - probeStart;
+            upstreams[name] = { status: "down", latencyMs };
+            logDiagnosticEvent(logger, {
+              domain: "service",
+              event: "gateway.upstream.health",
+              level: "warn",
+              reasonCode: "upstream_unavailable",
+              message: "Gateway upstream health probe failed",
+              outcome: "failed",
+              error: error instanceof Error ? error : new Error(String(error)),
+              serviceId: "gateway",
+              route: `${upstream.prefix}/health`,
+              evidence: {
+                upstreamId: name,
+                upstreamUrl: upstream.url,
+                latencyMs
+              }
+            });
+          }
+        });
+      }
+      const llmOk = adapters.llm?.available ?? false;
+      const allOk = Object.values(adapters).every((a) => a.available);
+      const snapshot = {
+        status: llmOk ? allOk ? "healthy" : "degraded" : "unhealthy",
+        version: "1.0",
+        uptime: Math.floor((Date.now() - startupTime) / 1e3),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        adapters,
+        upstreams
+      };
+      await cache.set(HEALTH_CACHE_KEY, snapshot, HEALTH_CACHE_TTL).catch(() => {
+      });
+      return snapshot;
+    };
+    scope.get("/health", { schema: { tags: ["System"], summary: "Gateway health check" } }, async () => {
+      return collectHealthSnapshot();
+    });
+    scope.get("/ready", { schema: { tags: ["System"], summary: "Gateway readiness check" } }, async (_request, reply) => {
+      const health = await collectHealthSnapshot();
+      const upstreams = health.upstreams ?? {};
+      const missingRequiredUpstreams = ["rest"].filter((id) => (upstreams[id]?.status ?? "down") !== "up");
+      const ready = missingRequiredUpstreams.length === 0;
+      return reply.code(ready ? 200 : 503).send(createServiceReadyResponse({
+        ready,
+        status: ready ? "ready" : "degraded",
+        reason: ready ? "ready" : `upstream_unavailable:${missingRequiredUpstreams.join(",")}`,
+        components: {
+          gatewayAdapters: {
+            ready: true
+          },
+          restUpstream: {
+            ready: (upstreams.rest?.status ?? "down") === "up",
+            status: upstreams.rest?.status ?? "down"
+          },
+          workflowUpstream: {
+            ready: (upstreams.workflow?.status ?? "down") === "up",
+            status: upstreams.workflow?.status ?? "down"
+          },
+          marketplaceUpstream: {
+            ready: (upstreams.marketplace?.status ?? "down") === "up",
+            status: upstreams.marketplace?.status ?? "down"
+          }
+        }
+      }));
+    });
+    scope.get("/metrics", { schema: { tags: ["Observability"], summary: "Gateway metrics in Prometheus format" } }, async (_request, reply) => {
+      const health = await collectHealthSnapshot();
+      const status = health.status ?? "healthy";
+      reply.header("Content-Type", "text/plain; version=0.0.4; charset=utf-8");
+      return observability.renderPrometheusMetrics(status);
+    });
+    scope.get("/observability/describe", {
+      schema: { tags: ["Observability"], summary: "Gateway observability contract descriptor" }
+    }, async () => observability.buildDescribe());
+    scope.get("/observability/health", {
+      schema: { tags: ["Observability"], summary: "Gateway observability health snapshot" }
+    }, async () => {
+      const health = await collectHealthSnapshot();
+      const adapterChecks = Object.entries(health.adapters ?? {}).map(([id, value]) => ({ id, available: !!value?.available, latencyMs: value?.latencyMs }));
+      const upstreamChecks = Object.entries(health.upstreams ?? {}).map(([id, value]) => ({ id, status: value?.status ?? "unknown", latencyMs: value?.latencyMs }));
+      const status = health.status ?? "healthy";
+      return observability.buildHealth({ status, adapterChecks, upstreamChecks });
+    });
+    if (!registry) {
+      gatewayLogger.warn("No persistent HostRegistry injected \u2014 hosts will be lost on restart");
+    }
+    const hostRegistry = registry ?? new HostRegistry(cache);
+    scope.post("/hosts/register", { schema: { tags: ["Hosts"], summary: "Register a host" } }, async (request, reply) => {
+      const parsed = HostRegistrationSchema.safeParse(request.body);
+      if (!parsed.success) {
+        return reply.code(400).send({ error: "Bad Request", issues: parsed.error.issues });
+      }
+      const result = await hostRegistry.register(parsed.data);
+      return reply.code(201).send({
+        hostId: result.descriptor.hostId,
+        machineToken: result.machineToken,
+        status: result.descriptor.status
+      });
+    });
+    scope.get("/hosts", { schema: { tags: ["Hosts"], summary: "List registered hosts" } }, async (request, reply) => {
+      const auth = request.authContext;
+      if (!auth) {
+        return reply.code(401).send({ error: "Unauthorized" });
+      }
+      const hosts = await hostRegistry.list(auth.namespaceId);
+      return { hosts };
+    });
+    scope.get("/hosts/:hostId", { schema: { tags: ["Hosts"], summary: "Get host by ID" } }, async (request, reply) => {
+      const auth = request.authContext;
+      if (!auth) {
+        return reply.code(401).send({ error: "Unauthorized" });
+      }
+      const { hostId } = request.params;
+      const host = await hostRegistry.get(hostId, auth.namespaceId);
+      if (!host) {
+        return reply.code(404).send({ error: "Host not found" });
+      }
+      return host;
+    });
+    scope.delete("/hosts/:hostId", { schema: { tags: ["Hosts"], summary: "Deregister a host" } }, async (request, reply) => {
+      const auth = request.authContext;
+      if (!auth) {
+        return reply.code(401).send({ error: "Unauthorized" });
+      }
+      const { hostId } = request.params;
+      const deleted = await hostRegistry.deregister(hostId, auth.namespaceId);
+      if (!deleted) {
+        return reply.code(404).send({ error: "Host not found" });
+      }
+      return reply.code(204).send();
+    });
+    registerExecuteRoutes(scope, logger);
+    registerLLMGatewayRoutes(scope, logger);
+    registerTelemetryRoutes(scope, logger);
+    registerPlatformRoutes(scope, logger);
+    registerAggregatedDocsRoutes(scope, cache);
+    const internalSecret = process.env.GATEWAY_INTERNAL_SECRET;
+    scope.post("/internal/dispatch", async (request, reply) => {
+      const provided = request.headers["x-internal-secret"];
+      if (!internalSecret || provided !== internalSecret) {
+        return reply.code(403).send({ error: "Forbidden" });
+      }
+      const body = request.body;
+      if (!body.namespaceId || !body.adapter || !body.method) {
+        return reply.code(400).send({ error: "Missing required fields: namespaceId, adapter, method" });
+      }
+      const hostId = body.hostId ?? globalDispatcher.firstHostWithCapability(body.namespaceId, body.adapter) ?? globalDispatcher.firstHost(body.namespaceId);
+      if (!hostId) {
+        return reply.code(503).send({
+          error: "No host connected",
+          namespaceId: body.namespaceId
+        });
+      }
+      try {
+        const result = await globalDispatcher.call(
+          body.namespaceId,
+          hostId,
+          body.adapter,
+          body.method,
+          body.args ?? []
+        );
+        return { result };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("Host not connected")) {
+          return reply.code(503).send({ error: message });
+        }
+        return reply.code(502).send({ error: message });
+      }
+    });
+    scope.post("/internal/resolve-host", async (request, reply) => {
+      const provided = request.headers["x-internal-secret"];
+      if (!internalSecret || provided !== internalSecret) {
+        return reply.code(403).send({ error: "Forbidden" });
+      }
+      const body = request.body;
+      const namespaceId = body.namespaceId ?? "default";
+      const target = body.target ?? {};
+      const strategy = target.hostSelection ?? "any-matching";
+      let hostId;
+      if (strategy === "pinned" && target.hostId) {
+        const host = await hostRegistry.get(target.hostId, namespaceId);
+        if (host?.status === "online" || host?.status === "reconnecting") {
+          hostId = target.hostId;
+        }
+      } else {
+        hostId = globalDispatcher.firstHostWithCapability(namespaceId, "execution");
+      }
+      if (!hostId) {
+        return reply.code(404).send({ error: "No matching host found" });
+      }
+      return { hostId, strategy, namespaceId };
+    });
+  });
+  await app.ready();
+  attachGatewayWs(app.server, cache, jwtConfig, logger, registry);
+  return app;
+}
+
+// src/bootstrap.ts
+async function bootstrap(repoRoot = process.cwd()) {
+  await createServiceBootstrap({ appId: "gateway", repoRoot });
+  const logger = createCorrelatedLogger(platform.logger, {
+    serviceId: "gateway",
+    logsSource: "gateway",
+    layer: "gateway",
+    service: "bootstrap",
+    operation: "gateway.bootstrap"
+  });
+  logger.info("Platform initialized", { repoRoot });
+  const config = await loadGatewayConfig(repoRoot);
+  logger.info("Gateway config loaded", {
+    port: config.port,
+    upstreams: Object.keys(config.upstreams)
+  });
+  let hostStore;
+  const db = platform.getAdapter("sqlDatabase");
+  if (db) {
+    hostStore = new SqliteHostStore(db);
+    logger.info("Host store: SQLite (persistent)");
+  } else {
+    logger.warn("Host store: none (cache-only, hosts will be lost on restart)");
+  }
+  const registry = new HostRegistry(platform.cache, hostStore);
+  let restoredCount = 0;
+  try {
+    restoredCount = await registry.restore();
+  } catch (error) {
+    logDiagnosticEvent(platform.logger, {
+      domain: "registry",
+      event: "gateway.hosts.restore",
+      level: "error",
+      reasonCode: "registry_restore_failed",
+      message: "Failed to restore gateway host registry",
+      outcome: "failed",
+      error: error instanceof Error ? error : new Error(String(error)),
+      serviceId: "gateway",
+      evidence: {
+        persistentStore: !!hostStore
+      }
+    });
+    throw error;
+  }
+  if (restoredCount > 0) {
+    logger.info("Restored hosts from store", { count: restoredCount });
+  }
+  for (const [token, entry] of Object.entries(config.staticTokens)) {
+    await platform.cache.set(`host:token:${token}`, entry);
+    logger.info("Static token seeded", { hostId: entry.hostId, namespaceId: entry.namespaceId });
+  }
+  const jwtSecret = process.env.GATEWAY_JWT_SECRET;
+  if (!jwtSecret) {
+    logger.warn("GATEWAY_JWT_SECRET not set \u2014 using insecure default (dev only!)");
+  }
+  const jwtConfig = { secret: jwtSecret ?? "dev-insecure-secret-change-me" };
+  const server = await createServer(config, platform.cache, platform.logger, jwtConfig, registry);
+  const address = await server.listen({ port: config.port, host: "0.0.0.0" });
+  logger.info("Gateway listening", { address });
+  const shutdown = async (signal) => {
+    logger.warn("Received shutdown signal", { signal });
+    await platform.shutdown();
+    await server.close();
+    logger.info("Gateway shutdown complete");
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+}
+
+// src/index.ts
+bootstrap(process.cwd()).catch((error) => {
+  console.error("Failed to start gateway:", error);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map