feat(dev): make the ai-gateway app startable from dev:start

pnpm dev:start ai-gateway starts apps/ai-gateway in its own opt-in group
on port 3010 plus the port offset, clear of the ports the web dev script
probes. Selecting it also syncs apps/web/.env.development.local, which the
app reads.

Author: chrarnoldus

DEVELOPMENT.md

@@ -240,6 +240,7 @@ should pass against the local PostgreSQL database.
 |---|---|
 | `KILO_PORT_OFFSET=auto pnpm dev:start` | Start all local services in a tmux dashboard with worktree-safe ports |
 | `pnpm dev:start agents cloud-agent-public-tunnels` | Same as `dev:start agents`, plus Cloudflare quick tunnels for sandbox-facing Worker/Next/session-ingest URLs |
+| `pnpm dev:start ai-gateway` | Also start the standalone AI gateway app (`apps/ai-gateway`) on port 3010 plus the port offset |
 | `pnpm dev:stop` | Stop the tmux session and all services |
 | `pnpm dev:env` | Sync `.dev.vars` files from `.env.local` (see [Worker `.dev.vars` setup](#worker-dev-vars-setup)) |
 | `pnpm dev:env --missing-secrets-only` | Sync env files and create missing local Secrets Store entries without refreshing existing secrets |

dev/local/env-sync/plan.ts

@@ -749,7 +749,9 @@ function computePlan(
 
   // --- .env.development.local changes ---
   const envDevLocalChanges: EnvDevLocalChange[] = [];
-  const processEnvDevLocal = !serviceFilter || serviceFilter.has('nextjs');
+  // apps/ai-gateway runs with the web app's env files (see its scripts/dev.sh).
+  const processEnvDevLocal =
+    !serviceFilter || serviceFilter.has('nextjs') || serviceFilter.has('ai-gateway');
 
   const envDevLocalExamplePath = path.join(repoRoot, 'apps/web/.env.development.local.example');
   if (processEnvDevLocal && fs.existsSync(envDevLocalExamplePath)) {

dev/local/services.test.ts

@@ -199,6 +199,29 @@ test('keeps auto routing workers in their own opt-in group', () => {
   assert.ok(!alwaysOn.includes('auto-routing-benchmark'));
 });
 
+test('keeps the AI gateway app in its own opt-in group', () => {
+  const service = getService('ai-gateway');
+
+  assert.equal(service.group, 'ai-gateway');
+  assert.equal(service.type, 'nextjs');
+  assert.equal(service.dir, 'apps/ai-gateway');
+  assert.equal(service.port, 3010 + portOffset);
+  assert.deepEqual(service.command, [
+    'env',
+    `AI_GATEWAY_PORT=${3010 + portOffset}`,
+    'pnpm',
+    'run',
+    'dev',
+  ]);
+  assert.deepEqual(resolveTargets(['ai-gateway']), [
+    'redis',
+    'postgres',
+    'redis-http',
+    'ai-gateway',
+  ]);
+  assert.ok(!resolveGroups(getAlwaysOnGroupIds()).includes('ai-gateway'));
+});
+
 test('registers user data export with worktree-aware ports and dependencies', () => {
   const service = getService('user-data-export');
 

dev/local/services.ts

@@ -63,6 +63,7 @@ const groups: ServiceGroup[] = [
   { id: 'deploy', label: 'Deploy', alwaysOn: false },
   { id: 'observability', label: 'Observability', alwaysOn: false },
   { id: 'auto-routing', label: 'Auto Routing', alwaysOn: false, sectionBreakBefore: true },
+  { id: 'ai-gateway', label: 'AI Gateway', alwaysOn: false },
   { id: 'mobile', label: 'Mobile', alwaysOn: false, sectionBreakBefore: true },
   { id: 'storybook', label: 'Storybook', alwaysOn: false, sectionBreakBefore: true },
   { id: 'deletion-mock', label: 'Deletion Mock', alwaysOn: false, sectionBreakBefore: true },
@@ -113,6 +114,13 @@ const serviceMeta: Record<string, ServiceMeta> = {
     dependsOn: ['postgres', 'nextjs'],
     dir: 'services/user-data-export',
   },
+  // The standalone AI gateway app (apps/ai-gateway). It serves the gateway
+  // routes the web app also serves, from the same database and Redis.
+  'ai-gateway': {
+    group: 'ai-gateway',
+    dependsOn: ['postgres', 'redis', 'redis-http'],
+    dir: 'apps/ai-gateway',
+  },
   // auto-routing (kilo-auto/efficient decision engine + benchmark runner)
   'auto-routing': {
     group: 'auto-routing',
@@ -675,6 +683,8 @@ function workerEnvPrefix(): string[] {
   return vars.length > 0 ? ['env', ...vars] : [];
 }
 
+const AI_GATEWAY_BASE_PORT = 3010;
+
 function buildServiceDefs(): ServiceDef[] {
   const repoRoot = REPO_ROOT;
   const defs: ServiceDef[] = [];
@@ -695,6 +705,23 @@ function buildServiceDefs(): ServiceDef[] {
       continue;
     }
 
+    if (name === 'ai-gateway') {
+      // Clear of the 3000-3009 range the web app's dev script probes. The port
+      // is passed as AI_GATEWAY_PORT because the session exports PORT for the
+      // web app.
+      const port = AI_GATEWAY_BASE_PORT + portOffset;
+      defs.push({
+        name,
+        type: 'nextjs',
+        dir: meta.dir ?? name,
+        port,
+        dependsOn: meta.dependsOn,
+        command: ['env', `AI_GATEWAY_PORT=${port}`, 'pnpm', 'run', 'dev'],
+        group: meta.group,
+      });
+      continue;
+    }
+
     if (name === 'storybook') {
       defs.push({
         name,