@kb-labs/gateway-app 0.2.0

package/src/llm/routes.ts

@@ -0,0 +1,343 @@
+/**
+ * @module AI Gateway — OpenAI-compatible LLM endpoint.
+ *
+ * Exposes `POST /api/v1/llm/chat/completions` using OpenAI ChatCompletion format.
+ * Model field is a tier abstraction (small/medium/large) — never a literal model name.
+ * All calls go through the platform LLM chain: QueuedLLM → AnalyticsLLM → LLMRouter → adapter.
+ */
+import type { FastifyInstance } from 'fastify';
+import { platform } from '@kb-labs/core-runtime';
+import type {
+  ILLM,
+  ILogger,
+  LLMMessage,
+  LLMToolCallOptions,
+  LLMTool,
+  ILLMRouter,
+  LLMTier,
+} from '@kb-labs/core-platform';
+import {
+  ChatCompletionRequestSchema,
+  type ChatCompletionRequest,
+  type ChatCompletionResponse,
+  type ChatCompletionChunk,
+} from '@kb-labs/gateway-contracts';
+
+// ── Tier resolution ───────────────────────────────────────────────────────
+
+function isLLMRouter(llm: ILLM): llm is ILLM & ILLMRouter {
+  return typeof (llm as any).resolveAdapter === 'function';
+}
+
+/**
+ * Resolve tier to a concrete ILLM adapter via LLMRouter.
+ * If no router (single-adapter setup), returns platform.llm directly.
+ */
+async function resolveLLMForTier(tier: LLMTier): Promise<ILLM | undefined> {
+  const llm = platform.llm;
+  if (!llm) {return undefined;}
+
+  if (isLLMRouter(llm)) {
+    const binding = await llm.resolveAdapter({ tier });
+    return binding.adapter;
+  }
+
+  // Single adapter — ignore tier, return as-is
+  return llm;
+}
+
+// ── Route registration ────────────────────────────────────────────────────
+
+/**
+ * Register AI Gateway routes on the given Fastify scope.
+ * The scope is expected to have the auth middleware already applied.
+ */
+export function registerLLMGatewayRoutes(app: FastifyInstance, logger: ILogger): void {
+  // hide: true — can stream SSE (text/event-stream), incompatible with OpenAPI response schema
+  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)}`;
+
+    // Resolve tier to LLM adapter
+    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,
+        },
+      });
+    }
+  });
+}
+
+// ── Non-streaming handler ─────────────────────────────────────────────────
+
+async function handleCompletionRequest(
+  reply: any,
+  llm: ILLM,
+  req: ChatCompletionRequest,
+  requestId: string,
+) {
+  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: LLMToolCallOptions = {
+      temperature: req.temperature,
+      maxTokens: req.max_tokens,
+      stop: normalizeStop(req.stop),
+      tools,
+      toolChoice: req.tool_choice as LLMToolCallOptions['toolChoice'],
+    };
+
+    const result = await llm.chatWithTools(messages, options);
+
+    const toolCalls = result.toolCalls?.map((tc) => ({
+      id: tc.id,
+      type: 'function' as const,
+      function: {
+        name: tc.name,
+        arguments: typeof tc.input === 'string' ? tc.input : JSON.stringify(tc.input),
+      },
+    }));
+
+    const finishReason =
+      result.stopReason === 'tool_use'
+        ? ('tool_calls' as const)
+        : result.stopReason === 'max_tokens'
+          ? ('length' as const)
+          : ('stop' as const);
+
+    const response: ChatCompletionResponse = {
+      id: requestId,
+      object: 'chat.completion',
+      created: Math.floor(startTime / 1000),
+      model: req.model,
+      choices: [
+        {
+          index: 0,
+          message: {
+            role: 'assistant',
+            content: result.content || null,
+            ...(toolCalls?.length ? { tool_calls: toolCalls } : {}),
+          },
+          finish_reason: finishReason,
+        },
+      ],
+      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);
+  }
+
+  // No tools — use simple complete()
+  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: ChatCompletionResponse = {
+    id: requestId,
+    object: 'chat.completion',
+    created: Math.floor(startTime / 1000),
+    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);
+}
+
+// ── Streaming handler ─────────────────────────────────────────────────────
+
+async function handleStreamingRequest(
+  reply: any,
+  llm: ILLM,
+  req: ChatCompletionRequest,
+  requestId: string,
+  logger: ILogger,
+) {
+  const created = Math.floor(Date.now() / 1000);
+
+  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: ChatCompletionChunk): void => {
+    if (!reply.raw.writableEnded) {
+      reply.raw.write(`data: ${JSON.stringify(chunk)}\n\n`);
+    }
+  };
+
+  const writeDone = (): void => {
+    if (!reply.raw.writableEnded) {
+      reply.raw.write('data: [DONE]\n\n');
+      reply.raw.end();
+    }
+  };
+
+  try {
+    // Initial role chunk
+    writeChunk({
+      id: requestId,
+      object: 'chat.completion.chunk',
+      created,
+      model: req.model,
+      choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }],
+    });
+
+    // Stream text from LLM
+    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 }],
+      });
+    }
+
+    // Finish chunk
+    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' } })}\n\n`,
+      );
+      reply.raw.end();
+    }
+  }
+
+  return reply;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+function toILLMMessages(req: ChatCompletionRequest): LLMMessage[] {
+  return req.messages.map((m) => {
+    const msg: LLMMessage = { 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: NonNullable<ChatCompletionRequest['tools']>): LLMTool[] {
+  return tools.map((t) => ({
+    name: t.function.name,
+    description: t.function.description ?? '',
+    inputSchema: t.function.parameters ?? {},
+  }));
+}
+
+function normalizeStop(stop: string | string[] | undefined): string[] | undefined {
+  if (!stop) {return undefined;}
+  return Array.isArray(stop) ? stop : [stop];
+}
+
+function safeJsonParse(str: string): unknown {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return str;
+  }
+}

package/src/manifest.ts

@@ -0,0 +1,21 @@
+import type { ServiceManifest } from '@kb-labs/plugin-contracts';
+
+export const manifest: ServiceManifest = {
+  schema: 'kb.service/1',
+  id: 'gateway',
+  name: 'Gateway',
+  version: '1.0.0',
+  description: 'Central router — aggregates REST API, Workflow, Marketplace',
+  runtime: {
+    entry: 'dist/index.js',
+    port: 4000,
+    healthCheck: '/health',
+  },
+  dependsOn: ['rest', 'workflow'],
+  env: {
+    PORT: { description: 'HTTP port', default: '4000' },
+    NODE_ENV: { description: 'Environment mode', default: 'development' },
+  },
+};
+
+export default manifest;

package/src/observability/collector.ts

@@ -0,0 +1,346 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest, HookHandlerDoneFunction } from 'fastify';
+import type { GatewayConfig } from '@kb-labs/gateway-contracts';
+import {
+  OBSERVABILITY_CONTRACT_VERSION,
+  OBSERVABILITY_SCHEMA,
+  CANONICAL_OBSERVABILITY_METRICS,
+  type ServiceHealthStatus,
+  type ObservabilityCheck,
+} from '@kb-labs/core-contracts';
+import type { ServiceObservabilityDescribe, ServiceObservabilityHealth } from '@kb-labs/core-contracts';
+import {
+  createServiceObservabilityDescribe,
+  createServiceObservabilityHealth,
+  OperationMetricsTracker,
+} from '@kb-labs/shared-http';
+import { hostname } from 'node:os';
+import { monitorEventLoopDelay, performance } from 'node:perf_hooks';
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    kbMetricsStart?: number;
+  }
+}
+
+type RouteStats = {
+  count: number;
+  totalDurationMs: number;
+  maxDurationMs: number;
+  errorCount: number;
+};
+
+function normalizeRoute(route: string | undefined): string {
+  if (!route) {
+    return 'unknown';
+  }
+  return route
+    .split('?')[0]!
+    .replace(/\/[0-9a-fA-F-]{6,}/g, '/:id');
+}
+
+function metricLine(name: string, value: number, labels?: Record<string, string>): string {
+  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}`;
+}
+
+export class GatewayObservabilityCollector {
+  private readonly instanceId = `${hostname()}:${process.pid}`;
+  private readonly eventLoop = monitorEventLoopDelay({ resolution: 20 });
+  private readonly routeStats = new Map<string, RouteStats>();
+  private readonly operationMetrics = new OperationMetricsTracker();
+  private readonly startedAt = Date.now();
+  private readonly dependencies;
+  private lastCpuUsage = process.cpuUsage();
+  private lastCpuTime = Date.now();
+  private intervalId: NodeJS.Timeout | null = null;
+  private activeOperations = 0;
+  private requestsTotal = 0;
+  private errorsTotal = 0;
+  private lastSnapshot = {
+    cpuPercent: 0,
+    rssBytes: process.memoryUsage().rss,
+    heapUsedBytes: process.memoryUsage().heapUsed,
+    eventLoopLagMs: 0,
+  };
+
+  constructor(private readonly config: GatewayConfig) {
+    this.dependencies = Object.keys(this.config.upstreams).map((serviceId) => ({
+      serviceId,
+      required: false,
+      description: 'Gateway upstream',
+    }));
+  }
+
+  register(server: unknown): void {
+    const hookServer = server as FastifyInstance;
+    this.eventLoop.enable();
+    this.intervalId = setInterval(() => this.captureRuntimeSnapshot(), 10_000);
+    this.captureRuntimeSnapshot();
+
+    hookServer.addHook('onRequest', (request: FastifyRequest, _reply: FastifyReply, done: HookHandlerDoneFunction) => {
+      request.kbMetricsStart = performance.now();
+      this.activeOperations += 1;
+      done();
+    });
+
+    hookServer.addHook('onResponse', (request: FastifyRequest, reply: FastifyReply, done: HookHandlerDoneFunction) => {
+      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: unknown, done: HookHandlerDoneFunction) => {
+      if (this.intervalId) {
+        clearInterval(this.intervalId);
+        this.intervalId = null;
+      }
+      this.eventLoop.disable();
+      done();
+    });
+  }
+
+  buildDescribe(): ServiceObservabilityDescribe {
+    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: {
+    status: ServiceHealthStatus;
+    adapterChecks: Array<{ id: string; available: boolean; latencyMs?: number }>;
+    upstreamChecks: Array<{ id: string; status: string; latencyMs?: number }>;
+  }): ServiceObservabilityHealth {
+    const checks: ObservabilityCheck[] = [
+      ...input.adapterChecks.map((entry): ObservabilityCheck => ({
+        id: `adapter:${entry.id}`,
+        status: entry.available ? 'ok' : 'warn',
+        latencyMs: entry.latencyMs,
+        message: entry.available ? 'Adapter available' : 'Adapter unavailable',
+      })),
+      ...input.upstreamChecks.map((entry): ObservabilityCheck => ({
+        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: new Date().toISOString(),
+      status: input.status,
+      uptimeSec: Math.floor((Date.now() - this.startedAt) / 1000),
+      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: ServiceHealthStatus): Promise<string> {
+    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')}\n`;
+  }
+
+  recordOperation(operation: string, durationMs = 0, status: 'ok' | 'error' = 'ok'): void {
+    this.operationMetrics.recordOperation(operation, durationMs, status);
+  }
+
+  observeOperation<T>(operation: string, work: () => T | Promise<T>): Promise<T> {
+    return this.operationMetrics.observeOperation(operation, work);
+  }
+
+  private captureRuntimeSnapshot(): void {
+    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) / 1000;
+    const memory = process.memoryUsage();
+    const eventLoopLagMs = Number((this.eventLoop.mean / 1_000_000).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: Array<{
+    operation: string;
+    count: number;
+    avgDurationMs: number;
+    maxDurationMs: number;
+    errorCount: number;
+  }>,
+  domainOperations: Array<{
+    operation: string;
+    count?: number;
+    avgDurationMs?: number;
+    maxDurationMs?: number;
+    errorCount?: number;
+  }>,
+  limit = 5,
+) {
+  const merged = new Map<string, {
+    operation: string;
+    count?: number;
+    avgDurationMs?: number;
+    maxDurationMs?: number;
+    errorCount?: number;
+  }>();
+
+  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];
+}