Merge pull request #393 from opticon454/feature-custom-llm-server-support

feat: Custom Model Endpoint Profiles (local or cloud, all harnesses)

src/web/routes/custom-model-routes.ts

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Custom Model Endpoint Profiles CRUD + discovery
+ * (deployment_plan.md). Endpoints are machine-level infra, like remote/docker
+ * hosts, so writes are admin-only in multi-user mode
+ * (`case-routes.ts`'s `/api/remote-hosts` is the pattern this mirrors).
+ *
+ * Discovery (`POST /:id/discover-models`) fetches `${baseUrl}/v1/models`.
+ * `isBlockedWebviewUrl()` is the same synchronous hostname/link-local/cloud-
+ * metadata check `webview-egress-policy.ts` uses for saved dashboard URLs —
+ * reused here as a save-time and discover-time guard. It does NOT re-check
+ * the DNS-RESOLVED address the way `webviewFetch()`'s undici lookup hook
+ * does; wiring that dispatcher-level guard here is a followup, not done in
+ * this pass, since this route is already admin-only in multi-user mode.
+ */
+
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import { ApiErrorCode, createErrorResponse, type ApiResponse } from '../../types.js';
+import { isAdmin, parseBody } from '../route-helpers.js';
+import { isMultiUserMode } from '../../config/multiuser.js';
+import { getDataDir } from '../../config/instance.js';
+import { isBlockedWebviewUrl } from '../webview-egress-policy.js';
+import { CustomModelHostSchema } from '../schemas.js';
+import { readCustomModelHosts, writeCustomModelHosts, type CustomModelHost } from '../../custom-model-hosts.js';
+
+const CODEMAN_CONFIG_DIR = getDataDir();
+const DISCOVER_TIMEOUT_MS = 8000;
+
+function adminOnly(req: FastifyRequest, reply: { code: (n: number) => unknown }): ApiResponse<never> | null {
+  if (!isMultiUserMode() || isAdmin(req)) return null;
+  reply.code(403);
+  return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Admin only in multi-user mode');
+}
+
+async function discoverModels(host: Pick<CustomModelHost, 'baseUrl' | 'apiKey' | 'authStyle'>): Promise<string[]> {
+  const headers: Record<string, string> = {};
+  const apiKey = host.apiKey?.trim();
+  // Exactly ONE header, never both — see custom-model-hosts.ts's CustomModelAuthStyle
+  // doc comment for why: sending both reliably HANGS some real servers.
+  const style = host.authStyle ?? 'bearer';
+  if (apiKey && style === 'bearer') headers.Authorization = `Bearer ${apiKey}`;
+  if (apiKey && style === 'api-key') headers['api-key'] = apiKey;
+
+  const res = await fetch(`${host.baseUrl.replace(/\/+$/, '')}/v1/models`, {
+    headers,
+    signal: AbortSignal.timeout(DISCOVER_TIMEOUT_MS),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const body = (await res.json()) as { data?: Array<{ id?: unknown }> };
+  return (body.data ?? []).map((m) => m.id).filter((id): id is string => typeof id === 'string' && id.length > 0);
+}
+
+export function registerCustomModelRoutes(app: FastifyInstance): void {
+  app.get('/api/model-endpoints', async (req) =>
+    isMultiUserMode() && !isAdmin(req) ? [] : readCustomModelHosts(CODEMAN_CONFIG_DIR)
+  );
+
+  app.post('/api/model-endpoints', async (req, reply): Promise<ApiResponse<{ host: CustomModelHost }>> => {
+    const denied = adminOnly(req, reply);
+    if (denied) return denied;
+    const host = parseBody(CustomModelHostSchema, req.body);
+    if (isBlockedWebviewUrl(host.baseUrl)) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Endpoint base URL is not allowed');
+    }
+    const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
+    if (hosts.some((item) => item.id === host.id)) {
+      return createErrorResponse(ApiErrorCode.ALREADY_EXISTS, 'Model endpoint already exists');
+    }
+    await writeCustomModelHosts(CODEMAN_CONFIG_DIR, [...hosts, host]);
+    return { success: true, data: { host } };
+  });
+
+  app.put('/api/model-endpoints/:id', async (req, reply): Promise<ApiResponse<{ host: CustomModelHost }>> => {
+    const denied = adminOnly(req, reply);
+    if (denied) return denied;
+    const { id } = req.params as { id: string };
+    const host = parseBody(CustomModelHostSchema, { ...(req.body as object), id });
+    if (isBlockedWebviewUrl(host.baseUrl)) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Endpoint base URL is not allowed');
+    }
+    const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
+    const index = hosts.findIndex((item) => item.id === id);
+    if (index === -1) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
+    const next = [...hosts];
+    next[index] = host;
+    await writeCustomModelHosts(CODEMAN_CONFIG_DIR, next);
+    return { success: true, data: { host } };
+  });
+
+  app.delete('/api/model-endpoints/:id', async (req, reply): Promise<ApiResponse<{ id: string }>> => {
+    const denied = adminOnly(req, reply);
+    if (denied) return denied;
+    const { id } = req.params as { id: string };
+    const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
+    await writeCustomModelHosts(
+      CODEMAN_CONFIG_DIR,
+      hosts.filter((item) => item.id !== id)
+    );
+    return { success: true, data: { id } };
+  });
+
+  app.post(
+    '/api/model-endpoints/:id/discover-models',
+    async (req, reply): Promise<ApiResponse<{ models: string[] }>> => {
+      const denied = adminOnly(req, reply);
+      if (denied) return denied;
+      const { id } = req.params as { id: string };
+      const hosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR);
+      const index = hosts.findIndex((item) => item.id === id);
+      if (index === -1) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
+      const host = hosts[index];
+      if (isBlockedWebviewUrl(host.baseUrl)) {
+        return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Endpoint base URL is not allowed');
+      }
+      try {
+        const models = await discoverModels(host);
+        const next = [...hosts];
+        next[index] = { ...host, models, lastDiscoveredAt: new Date().toISOString() };
+        await writeCustomModelHosts(CODEMAN_CONFIG_DIR, next);
+        return { success: true, data: { models } };
+      } catch (err) {
+        return createErrorResponse(
+          ApiErrorCode.OPERATION_FAILED,
+          `Could not reach endpoint: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  );
+}

src/web/routes/index.ts

@@ -27,3 +27,4 @@ export { registerWsRoutes } from './ws-routes.js';
 export { registerVoiceRoutes } from './voice-routes.js';
 export { registerWebviewRoutes, tryWebviewRefererFallback } from './webview-routes.js';
 export { registerTabLayoutRoutes } from './tab-layout-routes.js';
+export { registerCustomModelRoutes } from './custom-model-routes.js';

src/web/routes/session-routes.ts

@@ -51,7 +51,11 @@ import {
   SessionOrderUpdateSchema,
   SessionWaitQuerySchema,
   SessionWaitOutputQuerySchema,
+  CustomModelSelectionSchema,
 } from '../schemas.js';
+import { readCustomModelHosts } from '../../custom-model-hosts.js';
+import { buildCustomModelInjection } from '../../custom-model-injection.js';
+import { applyConfigDirInjection, removeConfigDir } from '../../custom-model-injection-apply.js';
 import { ownerLayoutKey } from '../../tab-layout-persistence.js';
 import { TabLayoutValidationError } from '../../tab-layout.js';
 import {
@@ -1152,6 +1156,80 @@ export function registerSessionRoutes(
     return { color: session.color };
   });
 
+  // ========== Custom Model Endpoint Profiles (deployment_plan.md) ==========
+  //
+  // Applies (or clears) a session's custom OpenAI-compatible endpoint selection and
+  // RESTARTS the pane's CLI process — these harnesses read endpoint config at process
+  // start, not per-turn, so a live hot-swap isn't possible (confirmed with the
+  // maintainer). Endpoints come from the admin-configured custom-model-hosts store
+  // (chunk 3's CRUD routes), never raw client-supplied env — that's what keeps this
+  // route safe to let any session owner call for their own session, unlike the
+  // generic envOverrides field the privilegedEnvKeys clamp exists to guard.
+  app.post('/api/sessions/:id/custom-model', async (req) => {
+    const { id } = req.params as { id: string };
+    const body = parseBody(CustomModelSelectionSchema, req.body, 'Invalid request body');
+    const session = findSessionOrFail(ctx, id, req);
+
+    if (session.isBusy()) {
+      return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy');
+    }
+
+    if ('clear' in body) {
+      const previousConfigDir = session.setCustomModel(undefined);
+      removeConfigDir(previousConfigDir);
+      const restarted = await session.restartCli();
+      persistAndBroadcastSession(ctx, session);
+      return { customModel: session.customModel, restarted };
+    }
+
+    const entry = getCli(session.mode);
+    if (!entry) {
+      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `No CLI registry entry for mode ${session.mode}`);
+    }
+    if (entry.capabilities.customModelInjection.kind === 'unsupported') {
+      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${session.mode} has no known custom-model mechanism`);
+    }
+
+    const hosts = await readCustomModelHosts(getDataDir());
+    const endpoint = hosts.find((h) => h.id === body.endpointId);
+    if (!endpoint) {
+      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
+    }
+
+    const injection = buildCustomModelInjection(entry, endpoint, body.modelId);
+
+    let envOverrides: Record<string, string>;
+    let envKeys: string[];
+    let configDir: string | undefined;
+
+    if (injection.kind === 'env') {
+      envOverrides = injection.envOverrides;
+      envKeys = Object.keys(injection.envOverrides);
+    } else if (injection.kind === 'configDir') {
+      // Isolated per-session dir — never the user's real CLI config path.
+      configDir = join(dataPath('custom-model-configs'), session.id);
+      envOverrides = applyConfigDirInjection(configDir, injection);
+      envKeys = Object.keys(envOverrides);
+    } else {
+      // 'unsupported' is already handled above; this keeps the switch exhaustive.
+      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${session.mode} has no known custom-model mechanism`);
+    }
+
+    const previousConfigDir = session.setCustomModel(
+      { endpointId: endpoint.id, modelId: body.modelId, label: endpoint.label, envKeys, configDir },
+      envOverrides
+    );
+    // Clean up the OLD config dir on disk, unless the new one happens to reuse the same
+    // path (same session, configDir kind again) — never delete the dir we just wrote.
+    if (previousConfigDir && previousConfigDir !== configDir) {
+      removeConfigDir(previousConfigDir);
+    }
+
+    const restarted = await session.restartCli();
+    persistAndBroadcastSession(ctx, session);
+    return { customModel: session.customModel, restarted };
+  });
+
   // ========== Delete Session ==========
 
   app.delete('/api/sessions/:id', async (req) => {

src/web/schemas.ts

@@ -739,6 +739,29 @@ export const RemoteHostSchema = z.object({
   commands: RemoteCommandOverridesSchema,
 });
 
+// Custom Model Endpoint Profiles (deployment_plan.md) — a user-configured custom
+// OpenAI-compatible endpoint, local (llama.cpp) or cloud (Azure AI Foundry, etc.).
+export const CustomModelHostSchema = z.object({
+  id: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid endpoint id'),
+  label: z.string().min(1).max(100),
+  baseUrl: z.string().url().max(2048),
+  apiKey: z.string().max(4096).optional(),
+  // No 'both': live-tested against a real server, sending both auth header
+  // conventions on one request reliably HANGS it — see custom-model-hosts.ts.
+  authStyle: z.enum(['bearer', 'api-key']).optional(),
+  models: z.array(z.string().max(200)).max(200).optional(),
+  lastDiscoveredAt: z.string().max(64).optional(),
+});
+
+/** POST /api/sessions/:id/custom-model — apply or clear a session's custom-model selection. */
+export const CustomModelSelectionSchema = z.union([
+  z.object({
+    endpointId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid endpoint id'),
+    modelId: z.string().min(1).max(200),
+  }),
+  z.object({ clear: z.literal(true) }),
+]);
+
 export const RemoteCaseLinkSchema = z.object({
   name: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid case name format'),
   hostId: z.string().regex(/^[a-zA-Z0-9_-]+$/, 'Invalid remote host id'),
@@ -1237,6 +1260,13 @@ export const SettingsUpdateSchema = z
      * stored profiles stay until DELETE /api/sessions/:id/intent.
      */
     readMyMindEnabled: z.boolean().optional(),
+    /**
+     * Custom Model Endpoint Profiles (deployment_plan.md): the toolbar picker that lets a
+     * session point at a user-configured custom OpenAI-compatible endpoint (local or
+     * cloud) instead of its native cloud backend. SYNCED, default OFF — endpoint entry,
+     * discovery, and the extra toolbar surface are all opt-in.
+     */
+    customModelEndpointsEnabled: z.boolean().optional(),
     /**
      * Read My Mind predictor model override. Empty/absent = the AI-checker
      * default (opus: prediction quality is the product and it runs only on an

src/web/server.ts

@@ -185,6 +185,7 @@ import {
   registerVoiceRoutes,
   registerWebviewRoutes,
   registerTabLayoutRoutes,
+  registerCustomModelRoutes,
   tryWebviewRefererFallback,
 } from './routes/index.js';
 import { isLostWebviewFrameNavigation } from './webview-proxy.js';
@@ -1070,6 +1071,7 @@ export class WebServer extends EventEmitter {
     registerOrchestratorRoutes(this.app, ctx);
     registerWebviewRoutes(this.app, ctx, this.basePath);
     registerTabLayoutRoutes(this.app, ctx);
+    registerCustomModelRoutes(this.app);
 
     // Cron: build the service from the same context, recompute
     // due times for any persisted jobs, then expose it to its routes.