Merge pull request #1074 from kaitranntt/kai/feat/1073-adaptive-proxy-ports

feat(proxy): add adaptive local port selection for OpenAI-compatible profiles

tests/e2e/proxy-command.e2e.test.ts

@@ -21,6 +21,27 @@ function runCli(args: string[], extraEnv: Record<string, string> = {}) {
   });
 }
 
+function writeJson(filePath: string, data: unknown) {
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+function createProfileConfig(profiles: Record<string, Record<string, string>>) {
+  const ccsDir = path.join(tempDir, '.ccs');
+  fs.mkdirSync(ccsDir, { recursive: true });
+  const configProfiles = Object.fromEntries(
+    Object.keys(profiles).map((name) => [name, path.join(ccsDir, `${name}.settings.json`)])
+  );
+  writeJson(path.join(ccsDir, 'config.json'), { profiles: configProfiles });
+  for (const [name, env] of Object.entries(profiles)) {
+    writeJson(configProfiles[name], { env });
+  }
+}
+
+function getRunningPort(statusOutput: string) {
+  const match = statusOutput.match(/Local URL: http:\/\/127\.0\.0\.1:(\d+)/);
+  expect(match).not.toBeNull();
+  return Number(match?.[1]);
+}
 beforeAll(() => {
   if (process.env.CCS_E2E_SKIP_BUILD === '1') {
     expect(fs.existsSync(DIST_ENTRY)).toBe(true);
@@ -54,6 +75,8 @@ describe('proxy command e2e', () => {
     expect(help.status).toBe(0);
     expect(help.stdout).toContain('Usage: ccs proxy <start|stop|status|activate> [profile] [options]');
     expect(help.stdout).toContain('stop [profile]    Stop the running proxy (or all proxies when omitted)');
+    expect(help.stdout).toContain('Pin an exact local proxy port for this launch');
+    expect(help.stdout).not.toContain('default: 3456');
   });
 
   it('shows the last-known proxy state when no proxy is currently running', async () => {
@@ -84,45 +107,29 @@ describe('proxy command e2e', () => {
     expect(status.stdout).toContain('Profile: stale');
   });
 
-  it('starts, reports status, activates, and stops via the built CLI', async () => {
-    const port = await getPort();
-    const ccsDir = path.join(tempDir, '.ccs');
-    fs.mkdirSync(ccsDir, { recursive: true });
-    const settingsPath = path.join(ccsDir, 'hf.settings.json');
-    fs.writeFileSync(
-      path.join(ccsDir, 'config.json'),
-      JSON.stringify({ profiles: { hf: settingsPath } }, null, 2),
-      'utf8'
-    );
-    fs.writeFileSync(
-      settingsPath,
-      JSON.stringify({
-        env: {
-          ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
-          ANTHROPIC_AUTH_TOKEN: 'ollama',
-          ANTHROPIC_MODEL: 'qwen3-coder',
-          CCS_DROID_PROVIDER: 'generic-chat-completion-api',
-        },
-      }),
-      'utf8'
-    );
-
-    const started = runCli(['proxy', 'start', 'hf', '--port', String(port), '--host', '127.0.0.1']);
-    expect(started.status).toBe(0);
-
-    const status = runCli(['proxy', 'status']);
+  it('surfaces the actual adaptive port in status and activation output', async () => {
+    createProfileConfig({
+      hf: {
+        ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
+        ANTHROPIC_AUTH_TOKEN: 'ollama',
+        ANTHROPIC_MODEL: 'qwen3-coder',
+        CCS_DROID_PROVIDER: 'generic-chat-completion-api',
+      },
+    });
+    expect(runCli(['proxy', 'start', 'hf', '--host', '127.0.0.1']).status).toBe(0);
+    const status = runCli(['proxy', 'status', 'hf']);
+    expect(status.status).toBe(0);
+    const port = getRunningPort(status.stdout);
     expect(status.stdout).toContain(`Proxy running on port ${port}`);
     expect(status.stdout).toContain('Host: 127.0.0.1');
     expect(status.stdout).toContain('Profile: hf');
-
-    const activate = runCli(['proxy', 'activate', '--shell', 'bash']);
+    const activate = runCli(['proxy', 'activate', 'hf', '--shell', 'bash']);
     expect(activate.stdout).toContain(`export ANTHROPIC_BASE_URL='http://127.0.0.1:${port}'`);
     expect(activate.stdout).toMatch(/export ANTHROPIC_AUTH_TOKEN='[a-f0-9]{48}'/);
     expect(activate.stdout).toContain("export DISABLE_TELEMETRY='1'");
     expect(activate.stdout).toContain("export DISABLE_COST_WARNINGS='1'");
     expect(activate.stdout).toContain("export API_TIMEOUT_MS='600000'");
     expect(activate.stdout).toContain("export NO_PROXY='127.0.0.1,localhost'");
-
     const activateFish = runCli(['proxy', 'activate', '--fish']);
     expect(activateFish.stdout).toContain(`set -gx ANTHROPIC_BASE_URL 'http://127.0.0.1:${port}'`);
 
@@ -147,41 +154,54 @@ describe('proxy command e2e', () => {
     expect(stopped.status).toBe(0);
   }, 35000);
 
+  it('respects an explicit --port override in status output', async () => {
+    const port = await getPort();
+    createProfileConfig({
+      hf: {
+        ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
+        ANTHROPIC_AUTH_TOKEN: 'ollama',
+        ANTHROPIC_MODEL: 'qwen3-coder',
+        CCS_DROID_PROVIDER: 'generic-chat-completion-api',
+      },
+    });
+    const started = runCli(['proxy', 'start', 'hf', '--port', String(port), '--host', '127.0.0.1']);
+    expect(started.status).toBe(0);
+    const status = runCli(['proxy', 'status', 'hf']);
+    expect(status.status).toBe(0);
+    expect(status.stdout).toContain(`Proxy running on port ${port}`);
+    expect(status.stdout).toContain(`Local URL: http://127.0.0.1:${port}`);
+  }, 35000);
+
+  it('rejects malformed explicit port values instead of coercing numeric prefixes', () => {
+    createProfileConfig({
+      hf: {
+        ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
+        ANTHROPIC_AUTH_TOKEN: 'ollama',
+        ANTHROPIC_MODEL: 'qwen3-coder',
+        CCS_DROID_PROVIDER: 'generic-chat-completion-api',
+      },
+    });
+
+    const invalid = runCli(['proxy', 'start', 'hf', '--port', '3456junk']);
+    expect(invalid.status).toBe(1);
+    expect(invalid.stderr).toContain('Invalid port: 3456junk');
+  });
+
   it('requires an explicit profile when activating with multiple running proxies', async () => {
     const firstPort = await getPort();
-    const ccsDir = path.join(tempDir, '.ccs');
-    fs.mkdirSync(ccsDir, { recursive: true });
-    const firstSettingsPath = path.join(ccsDir, 'ccg.settings.json');
-    const secondSettingsPath = path.join(ccsDir, 'ccgm.settings.json');
-    fs.writeFileSync(
-      path.join(ccsDir, 'config.json'),
-      JSON.stringify({ profiles: { ccg: firstSettingsPath, ccgm: secondSettingsPath } }, null, 2),
-      'utf8'
-    );
-    fs.writeFileSync(
-      firstSettingsPath,
-      JSON.stringify({
-        env: {
-          ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
-          ANTHROPIC_AUTH_TOKEN: 'ollama-ccg',
-          ANTHROPIC_MODEL: 'qwen3-coder',
-          CCS_DROID_PROVIDER: 'generic-chat-completion-api',
-        },
-      }),
-      'utf8'
-    );
-    fs.writeFileSync(
-      secondSettingsPath,
-      JSON.stringify({
-        env: {
-          ANTHROPIC_BASE_URL: 'https://api.openai.com/v1',
-          ANTHROPIC_AUTH_TOKEN: 'sk-ccgm',
-          ANTHROPIC_MODEL: 'gpt-4.1',
-        },
-      }),
-      'utf8'
-    );
-
+    createProfileConfig({
+      ccg: {
+        ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
+        ANTHROPIC_AUTH_TOKEN: 'ollama-ccg',
+        ANTHROPIC_MODEL: 'qwen3-coder',
+        CCS_DROID_PROVIDER: 'generic-chat-completion-api',
+      },
+      ccgm: {
+        ANTHROPIC_BASE_URL: 'https://api.openai.com/v1',
+        ANTHROPIC_AUTH_TOKEN: 'sk-ccgm',
+        ANTHROPIC_MODEL: 'gpt-4.1',
+      },
+    });
     expect(runCli(['proxy', 'start', 'ccg', '--port', String(firstPort)]).status).toBe(0);
     const secondPort = await getPort();
     expect(runCli(['proxy', 'start', 'ccgm', '--port', String(secondPort)]).status).toBe(0);

tests/integration/proxy/daemon-lifecycle.test.ts

@@ -9,6 +9,7 @@ import {
   startOpenAICompatProxy,
   stopOpenAICompatProxy,
 } from '../../../src/proxy/proxy-daemon';
+import { resolveOpenAICompatProxyPreferredPort } from '../../../src/proxy/proxy-port-resolver';
 import { resolveOpenAICompatProfileConfig } from '../../../src/proxy/profile-router';
 import {
   getLegacyOpenAICompatProxyPidPath,
@@ -159,6 +160,34 @@ describe('openai proxy daemon lifecycle', () => {
     expect(secondHealth.status).toBe(200);
   });
 
+  it('uses an adaptive implicit port instead of defaulting to 3456 for shared defaults', async () => {
+    const settingsPath = path.join(tempDir, 'adaptive-default.settings.json');
+    fs.writeFileSync(
+      settingsPath,
+      JSON.stringify({
+        env: {
+          ANTHROPIC_BASE_URL: 'https://api.openai.com/v1',
+          ANTHROPIC_AUTH_TOKEN: 'sk-adaptive-default',
+          ANTHROPIC_MODEL: 'gpt-4.1',
+        },
+      }),
+      'utf8'
+    );
+
+    const profile = resolveOpenAICompatProfileConfig('adaptive-default', settingsPath, {
+      ANTHROPIC_BASE_URL: 'https://api.openai.com/v1',
+      ANTHROPIC_AUTH_TOKEN: 'sk-adaptive-default',
+      ANTHROPIC_MODEL: 'gpt-4.1',
+    });
+    if (!profile) {
+      throw new Error('Expected adaptive-default OpenAI-compatible profile');
+    }
+
+    const started = await startOpenAICompatProxy(profile);
+    expect(started.success).toBe(true);
+    expect(started.port).not.toBe(3456);
+  });
+
   it('keeps a legacy singleton daemon visible across upgrade', async () => {
     const port = await getPort();
     const settingsPath = path.join(tempDir, 'legacy.settings.json');
@@ -317,6 +346,54 @@ describe('openai proxy daemon lifecycle', () => {
     }
   });
 
+  it('falls back when a configured shared proxy.port is occupied', async () => {
+    const occupiedPort = await getPort();
+    const server = Bun.serve({
+      port: occupiedPort,
+      hostname: '127.0.0.1',
+      fetch: () => new Response('busy'),
+    });
+
+    try {
+      mutateUnifiedConfig((config) => {
+        config.proxy = {
+          ...(config.proxy ?? {}),
+          port: occupiedPort,
+        };
+      });
+
+      const settingsPath = path.join(tempDir, 'shared-port.settings.json');
+      fs.writeFileSync(
+        settingsPath,
+        JSON.stringify({
+          env: {
+            ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
+            ANTHROPIC_AUTH_TOKEN: 'ollama-shared-port',
+            ANTHROPIC_MODEL: 'qwen3-coder',
+            CCS_DROID_PROVIDER: 'generic-chat-completion-api',
+          },
+        }),
+        'utf8'
+      );
+
+      const profile = resolveOpenAICompatProfileConfig('shared-port', settingsPath, {
+        ANTHROPIC_BASE_URL: 'http://127.0.0.1:11434',
+        ANTHROPIC_AUTH_TOKEN: 'ollama-shared-port',
+        ANTHROPIC_MODEL: 'qwen3-coder',
+        CCS_DROID_PROVIDER: 'generic-chat-completion-api',
+      });
+      if (!profile) {
+        throw new Error('Expected shared-port OpenAI-compatible profile');
+      }
+
+      const started = await startOpenAICompatProxy(profile);
+      expect(started.success).toBe(true);
+      expect(started.port).not.toBe(occupiedPort);
+    } finally {
+      server.stop(true);
+    }
+  });
+
   it('keeps the existing proxy running if replacement startup fails', async () => {
     const firstPort = await getPort();
     const occupiedPort = await getPort();
@@ -366,8 +443,8 @@ describe('openai proxy daemon lifecycle', () => {
     }
   });
 
-  it('reuses the last-known port even when it is outside the default fallback range', async () => {
-    const preferredPort = await getPort();
+  it('returns to the adaptive canonical port after a stale fallback session', async () => {
+    const stalePort = await getPort();
     const settingsPath = path.join(tempDir, 'outside-range.settings.json');
     fs.writeFileSync(
       settingsPath,
@@ -400,7 +477,7 @@ describe('openai proxy daemon lifecycle', () => {
           profileName: profile.profileName,
           settingsPath: profile.settingsPath,
           host: '127.0.0.1',
-          port: preferredPort,
+          port: stalePort,
           baseUrl: profile.baseUrl,
           authToken: 'stale-token',
           model: profile.model,
@@ -413,7 +490,57 @@ describe('openai proxy daemon lifecycle', () => {
 
     const started = await startOpenAICompatProxy(profile);
     expect(started.success).toBe(true);
-    expect(started.port).toBe(preferredPort);
+    expect(started.port).toBe(resolveOpenAICompatProxyPreferredPort('outside-range'));
+    expect(started.port).not.toBe(stalePort);
+  });
+
+  it('does not keep a stopped shared-default profile anchored to legacy port 3456', async () => {
+    const settingsPath = path.join(tempDir, 'legacy-shared-default.settings.json');
+    fs.writeFileSync(
+      settingsPath,
+      JSON.stringify({
+        env: {
+          ANTHROPIC_BASE_URL: 'https://api.openai.com/v1',
+          ANTHROPIC_AUTH_TOKEN: 'sk-legacy-shared-default',
+          ANTHROPIC_MODEL: 'gpt-4.1',
+        },
+      }),
+      'utf8'
+    );
+
+    const profile = resolveOpenAICompatProfileConfig('legacy-shared-default', settingsPath, {
+      ANTHROPIC_BASE_URL: 'https://api.openai.com/v1',
+      ANTHROPIC_AUTH_TOKEN: 'sk-legacy-shared-default',
+      ANTHROPIC_MODEL: 'gpt-4.1',
+    });
+    if (!profile) {
+      throw new Error('Expected legacy-shared-default OpenAI-compatible profile');
+    }
+
+    fs.mkdirSync(path.dirname(getOpenAICompatProxySessionPath('legacy-shared-default')), {
+      recursive: true,
+    });
+    fs.writeFileSync(
+      getOpenAICompatProxySessionPath('legacy-shared-default'),
+      JSON.stringify(
+        {
+          profileName: profile.profileName,
+          settingsPath: profile.settingsPath,
+          host: '127.0.0.1',
+          port: 3456,
+          baseUrl: profile.baseUrl,
+          authToken: 'stale-token',
+          model: profile.model,
+        },
+        null,
+        2
+      ) + '\n',
+      'utf8'
+    );
+
+    const started = await startOpenAICompatProxy(profile);
+    expect(started.success).toBe(true);
+    expect(started.port).not.toBe(3456);
   });
 
   it('stops legacy daemons even when the legacy session is missing a profile name', async () => {

tests/unit/proxy/proxy-port-resolver.test.ts

@@ -3,7 +3,11 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { mutateUnifiedConfig } from '../../../src/config/unified-config-loader';
-import { resolveOpenAICompatProxyPreferredPort } from '../../../src/proxy/proxy-port-resolver';
+import {
+  resolveOpenAICompatProxyAdaptivePort,
+  resolveOpenAICompatProxyPortPreference,
+  resolveOpenAICompatProxyPreferredPort,
+} from '../../../src/proxy/proxy-port-resolver';
 
 let originalCcsHome: string | undefined;
 let tempDir: string;
@@ -36,7 +40,69 @@ describe('resolveOpenAICompatProxyPreferredPort', () => {
     expect(resolveOpenAICompatProxyPreferredPort('ccgm')).toBe(3461);
   });
 
-  it('falls back to the shared default port when no profile mapping exists', () => {
-    expect(resolveOpenAICompatProxyPreferredPort('ccg')).toBe(3456);
+  it('returns a configured shared proxy port as a shared preference', () => {
+    mutateUnifiedConfig((config) => {
+      config.proxy = {
+        ...(config.proxy ?? {}),
+        port: 45_000,
+        profile_ports: {},
+      };
+    });
+
+    expect(resolveOpenAICompatProxyPortPreference('ccg')).toEqual({
+      port: 45_000,
+      source: 'shared',
+    });
+  });
+
+  it('treats legacy shared 3456 as an adaptive default on read', () => {
+    mutateUnifiedConfig((config) => {
+      config.proxy = {
+        ...(config.proxy ?? {}),
+        port: 3456,
+        profile_ports: {},
+      };
+    });
+
+    expect(resolveOpenAICompatProxyPortPreference('ccg')).toEqual({
+      port: resolveOpenAICompatProxyAdaptivePort('ccg'),
+      source: 'adaptive',
+    });
+  });
+
+  it('preserves an explicit shared 43456 port when the user configures it', () => {
+    mutateUnifiedConfig((config) => {
+      config.proxy = {
+        ...(config.proxy ?? {}),
+        port: 43_456,
+        profile_ports: {},
+      };
+    });
+
+    expect(resolveOpenAICompatProxyPortPreference('ccg')).toEqual({
+      port: 43_456,
+      source: 'shared',
+    });
+  });
+
+  it('falls back to an adaptive shared default when no profile mapping exists', () => {
+    const portPreference = resolveOpenAICompatProxyPortPreference('ccg');
+
+    expect(portPreference).toEqual({
+      port: resolveOpenAICompatProxyAdaptivePort('ccg'),
+      source: 'adaptive',
+    });
+    expect(resolveOpenAICompatProxyPreferredPort('ccg')).not.toBe(3456);
+  });
+
+  it('derives a stable adaptive default that does not keep all profiles on 3456', () => {
+    const first = resolveOpenAICompatProxyPreferredPort('ccg');
+    const second = resolveOpenAICompatProxyPreferredPort('ccg');
+    const other = resolveOpenAICompatProxyPreferredPort('ccgm');
+
+    expect(first).toBe(second);
+    expect(first).not.toBe(3456);
+    expect(other).not.toBe(3456);
+    expect(other).not.toBe(first);
   });
 });