refactor(ai-gateway): extract reusable package foundation

apps/web/package.json

@@ -39,6 +39,7 @@
     "@chat-adapter/state-memory": "^4.20.1",
     "@chat-adapter/state-redis": "^4.20.1",
     "google-auth-library": "^10.4.1",
+    "@kilocode/ai-gateway": "workspace:*",
     "@kilocode/db": "workspace:*",
     "@kilocode/encryption": "workspace:*",
     "@kilocode/kiloclaw-secret-catalog": "workspace:*",

apps/web/src/app/admin/alerting/use-add-model-search.ts

@@ -4,7 +4,7 @@ import { useMemo } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import type { ModelOption } from '@/app/admin/alerting/types';
 import { OpenRouterModelsResponseSchema } from '@/lib/organizations/organization-types';
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 import { z } from 'zod';
 
 type AddModelSearchResult = {

apps/web/src/app/admin/components/SafetyIdentifierHashGenerator.tsx

@@ -3,7 +3,7 @@
 import { useRef, useState } from 'react';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
-import { kilologHash } from '@/lib/ai-gateway/kilologHash';
+import { kilologHash } from '@kilocode/ai-gateway/kilolog-hash';
 
 export function SafetyIdentifierHashGenerator() {
   const [id, setId] = useState('');

apps/web/src/app/admin/gateway/RoutingContent.tsx

@@ -9,7 +9,7 @@ import { Input } from '@/components/ui/input';
 import { Textarea } from '@/components/ui/textarea';
 import { Label } from '@/components/ui/label';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
-import { DEFAULT_VERCEL_PERCENTAGE, NOTE_MAX_LENGTH } from '@/lib/ai-gateway/gateway-config';
+import { DEFAULT_VERCEL_PERCENTAGE, NOTE_MAX_LENGTH } from '@kilocode/ai-gateway/gateway-config';
 
 export function RoutingContent() {
   const trpc = useTRPC();

apps/web/src/app/api/openrouter/[...path]/route.ts

@@ -78,7 +78,7 @@ import {
   getToolsAvailable,
   getToolsUsed,
 } from '@/lib/ai-gateway/o11y/api-metrics.server';
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 import { isForbiddenFreeModel } from '@/lib/ai-gateway/forbidden-free-models';
 import { isCloudflareIP } from '@/lib/cloudflare-ip';
 import { isKiloAutoModel } from '@/lib/ai-gateway/kilo-auto';

apps/web/src/app/api/openrouter/embeddings/route.ts

@@ -30,7 +30,7 @@ import {
   type AnonymousUserContext,
 } from '@/lib/anonymous';
 import { emitApiMetricsForResponse } from '@/lib/ai-gateway/o11y/api-metrics.server';
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 import {
   buildUpstreamBody,
   type EmbeddingProxyRequest,

apps/web/src/components/organizations/OrganizationProvidersAndModelsConfigurationCard.tsx

@@ -13,7 +13,7 @@ import { AvailableModelsDialog } from './providers-and-models/AvailableModelsDia
 import { useOrganizationConfiguration } from './providers-and-models/useOrganizationConfiguration';
 import { useOpenRouterModelsAndProviders } from '@/app/api/openrouter/hooks';
 import type { ProviderSelection } from '@/components/models/util';
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 
 type OrganizationProvidersAndModelsConfigurationCardProps = {
   organizationId: string;

apps/web/src/components/organizations/providers-and-models/OrganizationProvidersAndModelsPage.tsx

@@ -7,7 +7,7 @@ import {
   useUpdateOrganizationSettings,
 } from '@/app/api/organizations/hooks';
 import { useOpenRouterModelsAndProviders } from '@/app/api/openrouter/hooks';
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 import { useRoleTesting } from '@/contexts/RoleTestingContext';
 import { OrganizationContextProvider } from '../OrganizationContext';
 import { OrganizationPageHeader } from '../OrganizationPageHeader';

apps/web/src/components/organizations/providers-and-models/allowLists.domain.ts

@@ -1,4 +1,4 @@
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 
 export type OpenRouterModelSlugSnapshot = {
   slug: string;

apps/web/src/components/organizations/providers-and-models/useProvidersAndModelsAllowListsState.ts

@@ -1,5 +1,5 @@
 import { useCallback, useMemo, useReducer } from 'react';
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 import {
   buildModelProvidersIndex,
   canonicalizeDenyList,

apps/web/src/lib/ai-gateway/gateway-config.ts

@@ -1,44 +1,9 @@
-import * as z from 'zod';
-
-export const DEFAULT_VERCEL_PERCENTAGE = 50;
-
-const vercelRoutingPercentage = z.number().int().min(0).max(100);
-
-export const NOTE_MAX_LENGTH = 500;
-
-const note = z.string().max(NOTE_MAX_LENGTH);
-
-export const GatewayConfigSchema = z.object({
-  vercel_routing_percentage: vercelRoutingPercentage.nullable(),
-  updated_at: z.string().nullable(),
-  updated_by: z.string().nullable(),
-  updated_by_email: z.string().nullable(),
-  note: note.nullable().default(null),
-});
-
-export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;
-
-export const DEFAULT_GATEWAY_CONFIG: GatewayConfig = {
-  vercel_routing_percentage: null,
-  updated_at: null,
-  updated_by: null,
-  updated_by_email: null,
-  note: null,
-};
-
-/**
- * Schema for parsing just the percentage from Redis (used on the hot path).
- *
- * `vercel_routing_percentage` is nullable because clearing the override in
- * the admin UI persists an explicit `null`. Callers should treat `null` as
- * "no override, use DEFAULT_VERCEL_PERCENTAGE".
- */
-export const GatewayPercentageSchema = z.object({
-  vercel_routing_percentage: vercelRoutingPercentage.nullable(),
-});
-
-/** Schema for the admin set-mutation input. */
-export const GatewayConfigInputSchema = z.object({
-  vercel_routing_percentage: vercelRoutingPercentage.nullable(),
-  note: note.nullable(),
-});
+export {
+  DEFAULT_GATEWAY_CONFIG,
+  DEFAULT_VERCEL_PERCENTAGE,
+  GatewayConfigInputSchema,
+  GatewayConfigSchema,
+  GatewayPercentageSchema,
+  NOTE_MAX_LENGTH,
+  type GatewayConfig,
+} from '@kilocode/ai-gateway/gateway-config';

apps/web/src/lib/ai-gateway/handleRequestLogging.ts

@@ -3,7 +3,7 @@ import { db } from '@/lib/drizzle';
 import { logExceptInTest } from '@/lib/utils.server';
 import { after } from 'next/server';
 import type { GatewayRequest } from '@/lib/ai-gateway/providers/openrouter/types';
-import { kilologHash } from '@/lib/ai-gateway/kilologHash';
+import { kilologHash } from '@kilocode/ai-gateway/kilolog-hash';
 import { createHash } from 'crypto';
 import { redisSet } from '@/lib/redis';
 import { requestLogRedisKey } from '@/lib/redis-keys';

apps/web/src/lib/ai-gateway/kilologHash.ts

@@ -1,7 +1 @@
-export async function kilologHash(id: string): Promise<string> {
-  const encoder = new TextEncoder();
-  const data = encoder.encode('kilolog|' + id);
-  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-  const hashArray = Array.from(new Uint8Array(hashBuffer));
-  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
-}
+export { kilologHash } from '@kilocode/ai-gateway/kilolog-hash';

apps/web/src/lib/ai-gateway/model-utils.ts

@@ -1,12 +1 @@
-/**
- * Shared model utilities that can be used on both client and server.
- * Keep this file free of server-only dependencies.
- */
-
-/**
- * Normalize a model ID by removing the `:free`, `:exacto`, etc. suffixes if present.
- */
-export function normalizeModelId(modelId: string): string {
-  const colonIndex = modelId.indexOf(':');
-  return colonIndex >= 0 ? modelId.substring(0, colonIndex) : modelId;
-}
+export { normalizeModelId } from '@kilocode/ai-gateway/model-utils';

apps/web/src/lib/ai-gateway/providers/openrouter/index.ts

@@ -18,7 +18,7 @@ import {
 import { AUTO_MODELS } from '@/lib/ai-gateway/kilo-auto';
 
 // Re-export from shared module for backwards compatibility
-export { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+export { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 
 function buildAutoModels(): OpenRouterModel[] {
   return AUTO_MODELS.map(m => ({

apps/web/src/lib/ai-gateway/providers/openrouter/models-by-provider-index.server.ts

@@ -1,6 +1,6 @@
 import { modelsByProvider } from '@kilocode/db/schema';
 import { db } from '@/lib/drizzle';
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 import type { NormalizedOpenRouterResponse } from '@/lib/ai-gateway/providers/openrouter/openrouter-types';
 import { desc } from 'drizzle-orm';
 

apps/web/src/lib/ai-gateway/providers/vercel/index.ts

@@ -22,7 +22,7 @@ import { createCachedFetch } from '@/lib/cached-fetch';
 import {
   GatewayPercentageSchema,
   DEFAULT_VERCEL_PERCENTAGE,
-} from '@/lib/ai-gateway/gateway-config';
+} from '@kilocode/ai-gateway/gateway-config';
 import { VERCEL_ROUTING_REDIS_KEY } from '@/lib/redis-keys';
 import { getRandomNumber } from '@/lib/ai-gateway/getRandomNumber';
 import { getVercelModels } from '@/lib/ai-gateway/providers/gateway-models-cache';

apps/web/src/lib/model-allow.server.ts

@@ -1,5 +1,5 @@
 import 'server-only';
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 import { getProviderSlugsForModel } from '@/lib/ai-gateway/providers/openrouter/models-by-provider-index.server';
 
 export type ProviderAwareAllowPredicate = (modelId: string) => Promise<boolean>;

apps/web/src/routers/admin-alerting-router.ts

@@ -1,7 +1,7 @@
 import { adminProcedure, createTRPCRouter } from '@/lib/trpc/init';
 import { z } from 'zod';
 import { fetchO11yJson, O11yRequestError } from '@/lib/ai-gateway/o11y-client';
-import { normalizeModelId } from '@/lib/ai-gateway/model-utils';
+import { normalizeModelId } from '@kilocode/ai-gateway/model-utils';
 import { TRPCError } from '@trpc/server';
 
 const AlertingConfigSchema = z.object({

apps/web/src/routers/admin/gateway-config-router.ts

@@ -1,12 +1,12 @@
 import { adminProcedure, createTRPCRouter } from '@/lib/trpc/init';
 import { redisGet, redisSet } from '@/lib/redis';
 import {
-  GatewayConfigSchema,
-  GatewayConfigInputSchema,
   DEFAULT_GATEWAY_CONFIG,
-} from '@/lib/ai-gateway/gateway-config';
+  GatewayConfigInputSchema,
+  GatewayConfigSchema,
+} from '@kilocode/ai-gateway/gateway-config';
 import { VERCEL_ROUTING_REDIS_KEY } from '@/lib/redis-keys';
-import type { GatewayConfig } from '@/lib/ai-gateway/gateway-config';
+import type { GatewayConfig } from '@kilocode/ai-gateway/gateway-config';
 import { TRPCError } from '@trpc/server';
 
 async function readConfig(): Promise<GatewayConfig> {

apps/web/tsconfig.json

@@ -10,6 +10,8 @@
     "forceConsistentCasingInFileNames": true,
     "paths": {
       "@/*": ["./src/*"],
+      "@kilocode/ai-gateway": ["../../packages/ai-gateway/src/index.ts"],
+      "@kilocode/ai-gateway/*": ["../../packages/ai-gateway/src/*"],
       "@kilocode/db": ["../../packages/db/src/index.ts"],
       "@kilocode/db/*": ["../../packages/db/src/*"],
       "@kilocode/encryption": ["../../packages/encryption/src/index.ts"],

packages/ai-gateway/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@kilocode/ai-gateway",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./adapters": "./src/adapters/index.ts",
+    "./gateway-config": "./src/gateway-config.ts",
+    "./http": "./src/http/index.ts",
+    "./kilolog-hash": "./src/kilolog-hash.ts",
+    "./model-utils": "./src/model-utils.ts",
+    "./observability": "./src/observability/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit",
+    "lint": "pnpm -w exec oxlint --config .oxlintrc.json packages/ai-gateway/src"
+  },
+  "dependencies": {
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "catalog:",
+    "typescript": "catalog:"
+  }
+}

packages/ai-gateway/src/adapters/index.ts

@@ -0,0 +1,15 @@
+export type BackgroundTask = Promise<unknown> | (() => unknown);
+
+export type BackgroundScheduler = (task: BackgroundTask) => void;
+
+export const runDetached: BackgroundScheduler = task => {
+  const run = typeof task === 'function' ? task : () => task;
+  queueMicrotask(() => {
+    void Promise.resolve().then(run);
+  });
+};
+
+export type KeyValueStore = {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+};

packages/ai-gateway/src/gateway-config.ts

@@ -0,0 +1,36 @@
+import * as z from 'zod';
+
+export const DEFAULT_VERCEL_PERCENTAGE = 50;
+
+const vercelRoutingPercentage = z.number().int().min(0).max(100);
+
+export const NOTE_MAX_LENGTH = 500;
+
+const note = z.string().max(NOTE_MAX_LENGTH);
+
+export const GatewayConfigSchema = z.object({
+  vercel_routing_percentage: vercelRoutingPercentage.nullable(),
+  updated_at: z.string().nullable(),
+  updated_by: z.string().nullable(),
+  updated_by_email: z.string().nullable(),
+  note: note.nullable().default(null),
+});
+
+export type GatewayConfig = z.infer<typeof GatewayConfigSchema>;
+
+export const DEFAULT_GATEWAY_CONFIG: GatewayConfig = {
+  vercel_routing_percentage: null,
+  updated_at: null,
+  updated_by: null,
+  updated_by_email: null,
+  note: null,
+};
+
+export const GatewayPercentageSchema = z.object({
+  vercel_routing_percentage: vercelRoutingPercentage.nullable(),
+});
+
+export const GatewayConfigInputSchema = z.object({
+  vercel_routing_percentage: vercelRoutingPercentage.nullable(),
+  note: note.nullable(),
+});

packages/ai-gateway/src/http/index.ts

@@ -0,0 +1,31 @@
+export type JsonResponseInit = ResponseInit & {
+  headers?: HeadersInit;
+};
+
+export function jsonResponse(body: unknown, init: JsonResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  if (!headers.has('content-type')) {
+    headers.set('content-type', 'application/json');
+  }
+  return new Response(JSON.stringify(body), { ...init, headers });
+}
+
+export function getSafeProxyOutputHeaders(response: Response): Headers {
+  const outputHeaders = new Headers();
+
+  for (const headerKey of ['date', 'content-type', 'request-id']) {
+    const value = response.headers.get(headerKey);
+    if (value) outputHeaders.set(headerKey, value);
+  }
+  outputHeaders.set('Content-Encoding', 'identity');
+
+  return outputHeaders;
+}
+
+export function wrapInSafeResponse(response: Response): Response {
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: getSafeProxyOutputHeaders(response),
+  });
+}

packages/ai-gateway/src/index.ts

@@ -0,0 +1,6 @@
+export * from './adapters';
+export * from './gateway-config';
+export * from './http';
+export * from './kilolog-hash';
+export * from './model-utils';
+export * from './observability';

packages/ai-gateway/src/kilolog-hash.ts

@@ -0,0 +1,7 @@
+export async function kilologHash(id: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode('kilolog|' + id);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}

packages/ai-gateway/src/model-utils.ts

@@ -0,0 +1,7 @@
+/**
+ * Normalize a model ID by removing the `:free`, `:exacto`, etc. suffixes if present.
+ */
+export function normalizeModelId(modelId: string): string {
+  const colonIndex = modelId.indexOf(':');
+  return colonIndex >= 0 ? modelId.substring(0, colonIndex) : modelId;
+}

packages/ai-gateway/src/observability/index.ts

@@ -0,0 +1,25 @@
+export type GatewayLogContext = Record<string, unknown>;
+
+export type GatewayLogger = {
+  debug(message: string, context?: GatewayLogContext): void;
+  info(message: string, context?: GatewayLogContext): void;
+  warn(message: string, context?: GatewayLogContext): void;
+  error(message: string, context?: GatewayLogContext): void;
+};
+
+export type GatewayTelemetry = {
+  captureException(error: unknown, context?: GatewayLogContext): void;
+  captureMessage(message: string, context?: GatewayLogContext): void;
+};
+
+export const noopGatewayLogger: GatewayLogger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};
+
+export const noopGatewayTelemetry: GatewayTelemetry = {
+  captureException() {},
+  captureMessage() {},
+};