Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

25.8 KB
Raw Blame
import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
import type { IncomingMessage, ServerResponse } from 'node:http';
import { dirname, resolve, sep } from 'node:path';
import {
  ApiConfigSuccessSchema,
  type ConfigDiagnosticsReport,
  ConfigDiagnosticsReportSchema,
  DEFAULT_EMBEDDINGS_BASE_URL,
  EmbedDetectSuccessSchema,
  EmptyRequestSchema,
  isHiddenDocName,
  type Principal,
  PrincipalSuccessSchema,
  type RescueEntryFlat,
  type RescueEntryTimeline,
  RescueListSuccessSchema,
  SemanticIndexStatusSchema,
  type SemanticProviderErrorReason,
  ServerInfoSuccessSchema,
  WorkspaceSuccessSchema,
} from '@inkeep/open-knowledge-core';
import { z } from 'zod';
import {
  ACP_AGENT_HARNESS_CLIS,
  type AcpHarnessAvailability,
} from '../acp/harness-availability.ts';
import { mergedEnv, withLoginShellPathEnv } from '../acp/launch.ts';
import { getSharedLoginShellPathProvider } from '../acp/login-shell-path.ts';
import { codexCandidates } from '../acp/model-discovery/candidates.ts';
import { probeCodexCatalog } from '../acp/model-discovery/codex-probe.ts';
import {
  type AcpRegistry,
  type CustomAgentEntry,
  FEATURED_AGENT_IDS,
  registryPlatformKey,
} from '../acp/registry.ts';
import { MAX_ACP_THREADS } from '../acp/thread-manager.ts';
import { getBootTimings } from '../boot-timings.ts';
import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';
import { collabUrlFromRequestHeaders } from '../collab-bootstrap-url.ts';
import { getLocalDir } from '../config/paths.ts';
import { isSupportedDocFile, stripDocExtension } from '../doc-extensions.ts';
import { deriveDetection, embedProbeRing } from '../embed-probe.ts';
import {
  FileEmbeddingsBackend,
  type ResolvedSemanticConfig,
  resolveEmbeddingsCredential,
  type SemanticSearchService,
} from '../embeddings/index.ts';
import type { FileIndexEntry } from '../file-watcher.ts';
import { tracedRmdirSync, tracedUnlinkSync } from '../fs-traced.ts';
import { type createInstalledAgentsProbe, handleInstalledAgents } from '../handoff-api.ts';
import type { PinoLogger } from '../logger.ts';
import { isWithinDir } from '../path-utils.ts';
import { readServerLock } from '../server-lock.ts';
import { listRescueCheckpoints, type ShadowRef, type TimelineRescueEntry } from '../shadow-repo.ts';
import { PROTOCOL_VERSION, RUNTIME_VERSION } from '../version-constants.ts';
import type { ApiRouteTable } from './api-pipeline.ts';
import { errorResponse } from './error-response.ts';
import { errnoCode } from './handler-utils.ts';
import { getRequestId } from './request-id.ts';
import { withValidation } from './request-validation.ts';
import { successResponse } from './success-response.ts';

export interface ConfigSystemRouteDeps {
  contentDir: string;
  projectDir: string | undefined;
  ephemeral: boolean;
  log: PinoLogger;
  ready: Promise<void> | undefined;
  serverInstanceId: string;
  getDiskAckSVs: (() => Record<string, string>) | undefined;
  getCollabClientCount: (() => number) | undefined;
  getConfigDiagnostics: (() => ConfigDiagnosticsReport) | undefined;
  acpRegistry: AcpRegistry | undefined;
  loadAcpCustomAgents: (() => Promise<CustomAgentEntry[]>) | undefined;
  acpHarnessAvailability: () => Promise<AcpHarnessAvailability>;
  isRoutePeerAdmitted: (remoteAddress: string | undefined) => boolean;
  isAllowedWorkspaceHostHeader: (host: string | undefined) => boolean;
  checkLocalOpSecurity: (
    req: IncomingMessage,
    res: ServerResponse,
    opts: { handler: string },
  ) => boolean;
  getPrincipal: (() => Principal | null) | undefined;
  semanticSearch: Pick<SemanticSearchService, 'getStatus'> | undefined;
  readSemanticProviderConfig: (() => ResolvedSemanticConfig) | undefined;
  embeddingsSecretsFile: string | undefined;
  getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;
  shadowRef: ShadowRef | undefined;
  getCurrentBranch: (() => string | null) | undefined;
  getReportedBranch: (() => string | null) | undefined;
  installedAgentsCache: Pick<ReturnType<typeof createInstalledAgentsProbe>, 'probeAll'>;
}

export interface ConfigSystemRoutes {
  paths: readonly string[];
  table: ApiRouteTable;
}

export function createConfigSystemRoutes(deps: ConfigSystemRouteDeps): ConfigSystemRoutes {
  const {
    contentDir,
    projectDir,
    ephemeral,
    log,
    ready,
    serverInstanceId,
    getDiskAckSVs,
    getCollabClientCount,
    getConfigDiagnostics,
    acpRegistry,
    loadAcpCustomAgents,
    acpHarnessAvailability,
    isRoutePeerAdmitted,
    isAllowedWorkspaceHostHeader,
    checkLocalOpSecurity,
    getPrincipal,
    semanticSearch,
    readSemanticProviderConfig,
    embeddingsSecretsFile,
    getFileIndex,
    shadowRef,
    getCurrentBranch,
    getReportedBranch,
    installedAgentsCache,
  } = deps;

  const handleServerInfo = withValidation(
    EmptyRequestSchema,
    async (_req, res) => {
      try {
        if (ready) {
          await ready.catch((err: unknown) => {
            log.warn(
              { err, handler: 'server-info' },
              '[api] ready gate rejected — responding with current state',
            );
          });
        }
        const currentBranch = getReportedBranch?.() ?? undefined;
        const currentDiskAckSVs = getDiskAckSVs?.();
        const boot = getBootTimings();
        const collabClients = getCollabClientCount?.();
        successResponse(
          res,
          200,
          ServerInfoSuccessSchema,
          {
            serverInstanceId,
            ...(currentBranch !== undefined ? { currentBranch } : {}),
            ...(currentDiskAckSVs !== undefined ? { currentDiskAckSVs } : {}),
            ...(boot !== undefined ? { boot } : {}),
            ...(collabClients !== undefined ? { collabClients } : {}),
            runtimeVersion: RUNTIME_VERSION,
            protocolVersion: PROTOCOL_VERSION,
          },
          {
            handler: 'server-info',
            extraHeaders: { 'Cache-Control': 'no-store' },
          },
        );
      } catch (e) {
        errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
          handler: 'server-info',
          cause: e,
        });
      }
    },
    { handler: 'server-info', method: 'GET', skipBodyParse: true },
  );

  const AcpCatalogAgentSchema = z.object({
    id: z.string(),
    name: z.string(),
    version: z.string(),
    description: z.string().optional(),
    license: z.string().optional(),
    iconUrl: z.string().optional(),
    website: z.string().optional(),
    source: z.enum(['registry', 'custom']),
    supported: z.boolean(),
    featured: z.boolean(),
    harness: z
      .object({
        cli: z.enum(['claude', 'codex', 'cursor', 'gemini', 'opencode', 'pi']),
        availability: z.enum(['present', 'not-found', 'unknown']),
        credentials: z.enum(['present', 'unknown']),
      })
      .optional(),
  });
  const AcpCatalogSuccessSchema = z.object({
    agents: z.array(AcpCatalogAgentSchema),
    stale: z.boolean(),
    maxThreads: z.number(),
  });

  const AcpModelsSuccessSchema = z.object({
    agentId: z.string(),
    reason: z.string().nullable(),
    candidates: z.array(
      z.object({
        value: z.string(),
        label: z.string(),
        description: z.string().nullable(),
        group: z.string().nullable(),
        contextChoices: z.array(z.number()),
        context: z.object({ effectiveTokens: z.number(), origin: z.string() }).nullable(),
        selectability: z.string(),
        setPhase: z.string(),
      }),
    ),
  });

  const handleAcpModels = withValidation(
    EmptyRequestSchema,
    async (req, res) => {
      const agentId = new URL(req.url ?? '', 'http://localhost').searchParams.get('agent') ?? '';
      const empty = (reason: string) =>
        successResponse(res, 200, AcpModelsSuccessSchema, { agentId, candidates: [], reason });
      if (agentId === '') {
        errorResponse(res, 400, 'urn:ok:error:invalid-request', 'An agent id is required.', {
          handler: 'acp-models',
        });
        return;
      }
      if (agentId !== 'codex-acp') {
        empty('unsupported');
        return;
      }
      const availability = await acpHarnessAvailability();
      if (availability.codex?.availability !== 'present') {
        empty('unavailable');
        return;
      }
      const spawnEnv = mergedEnv();
      let probe = await probeCodexCatalog('codex', spawnEnv);
      if (probe.outcome === 'not-found') {
        const loginShellPath = await getSharedLoginShellPathProvider(log)();
        if (loginShellPath !== null) {
          probe = await probeCodexCatalog('codex', withLoginShellPathEnv(spawnEnv, loginShellPath));
        }
      }
      if (probe.outcome !== 'ok') {
        log.warn({ agentId, outcome: probe.outcome }, '[acp-models] codex catalog probe failed');
        empty('unavailable');
        return;
      }
      const catalog = probe.models;
      if (catalog.length === 0) {
        empty('unavailable');
        return;
      }
      const fingerprint = {
        harness: 'codex',
        cliVersion: null,
        adapterVersion: null,
        endpoint: null,
        account: null,
      };
      successResponse(res, 200, AcpModelsSuccessSchema, {
        agentId,
        reason: null,
        candidates: codexCandidates(catalog, fingerprint, Date.now()).map((c) => ({
          value: c.value,
          label: c.label,
          description: c.description,
          group: c.group,
          contextChoices: [...c.contextChoices],
          context: c.context,
          selectability: c.selectability,
          setPhase: c.setPhase,
        })),
      });
    },
    { handler: 'acp-models' },
  );

  const handleAcpCatalog = withValidation(
    EmptyRequestSchema,
    async (_req, res) => {
      if (acpRegistry === undefined) {
        errorResponse(res, 404, 'urn:ok:error:not-found', 'ACP catalog unavailable.', {
          handler: 'acp-catalog',
        });
        return;
      }
      try {
        const platform = registryPlatformKey();
        const { agents, stale } = await acpRegistry.getCatalog();
        const custom = (await loadAcpCustomAgents?.()) ?? [];
        const harnessAvailability = await acpHarnessAvailability();
        const rows = [
          ...agents.map((a) => {
            const harnessCli = ACP_AGENT_HARNESS_CLIS[a.id];
            return {
              id: a.id,
              name: a.name,
              version: a.version,
              ...(a.description !== undefined ? { description: a.description } : {}),
              ...(a.license !== undefined ? { license: a.license } : {}),
              ...(a.icon !== undefined ? { iconUrl: a.icon } : {}),
              ...(a.website !== undefined ? { website: a.website } : {}),
              source: 'registry' as const,
              supported:
                a.distribution.npx !== undefined ||
                a.distribution.uvx !== undefined ||
                (platform !== null && a.distribution.binary?.[platform] !== undefined),
              featured: FEATURED_AGENT_IDS.includes(a.id),
              ...(harnessCli !== undefined
                ? {
                    harness: {
                      cli: harnessCli,
                      availability: harnessAvailability[harnessCli]?.availability ?? 'unknown',
                      credentials: harnessAvailability[harnessCli]?.credentials ?? 'unknown',
                    },
                  }
                : {}),
            };
          }),
          ...custom.map((c: CustomAgentEntry) => ({
            id: c.id,
            name: c.name,
            version: 'custom',
            source: 'custom' as const,
            supported: true,
            featured: false,
          })),
        ];
        successResponse(
          res,
          200,
          AcpCatalogSuccessSchema,
          { agents: rows, stale, maxThreads: MAX_ACP_THREADS },
          { handler: 'acp-catalog', extraHeaders: { 'Cache-Control': 'no-store' } },
        );
      } catch (e) {
        errorResponse(
          res,
          502,
          'urn:ok:error:registry-unreachable',
          'Agent registry unreachable.',
          {
            handler: 'acp-catalog',
            cause: e,
          },
        );
      }
    },
    { handler: 'acp-catalog', method: 'GET', skipBodyParse: true },
  );

  async function handlePrincipal(req: IncomingMessage, res: ServerResponse): Promise<void> {
    if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {
      errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
        handler: 'principal',
      });
      return;
    }
    if (!isAllowedWorkspaceHostHeader(req.headers.host)) {
      errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
        handler: 'principal',
      });
      return;
    }
    if (req.method !== 'GET') {
      errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
        handler: 'principal',
        extraHeaders: { Allow: 'GET' },
      });
      return;
    }
    const principal = getPrincipal?.() ?? null;
    if (!principal) {
      errorResponse(res, 404, 'urn:ok:error:principal-not-available', 'Principal not available.', {
        handler: 'principal',
      });
      return;
    }
    successResponse(res, 200, PrincipalSuccessSchema, principal, { handler: 'principal' });
  }

  async function handleEmbedDetect(req: IncomingMessage, res: ServerResponse): Promise<void> {
    if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {
      errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
        handler: 'embed-detect',
      });
      return;
    }
    if (!isAllowedWorkspaceHostHeader(req.headers.host)) {
      errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
        handler: 'embed-detect',
      });
      return;
    }
    if (req.method !== 'GET') {
      errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
        handler: 'embed-detect',
        extraHeaders: { Allow: 'GET' },
      });
      return;
    }
    const entries = embedProbeRing.read();
    successResponse(
      res,
      200,
      EmbedDetectSuccessSchema,
      {
        entries,
        count: entries.length,
        detection: deriveDetection(entries[0]),
      },
      { handler: 'embed-detect' },
    );
  }

  async function handleWorkspace(req: IncomingMessage, res: ServerResponse): Promise<void> {
    if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {
      errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {
        handler: 'workspace',
      });
      return;
    }
    if (!isAllowedWorkspaceHostHeader(req.headers.host)) {
      errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {
        handler: 'workspace',
      });
      return;
    }
    if (req.method !== 'GET') {
      errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
        handler: 'workspace',
        extraHeaders: { Allow: 'GET' },
      });
      return;
    }
    const resolvedRoot = resolve(contentDir);
    let resolvedContentDir = resolvedRoot;
    let symlinkResolved = true;
    try {
      resolvedContentDir = realpathSync(resolvedRoot);
    } catch (err) {
      const code = errnoCode(err);
      if (code === 'ENOENT') {
        log.warn(
          { path: resolvedRoot },
          '[workspace] contentDir does not exist; returning unresolved path',
        );
        symlinkResolved = false;
      } else {
        log.warn({ path: resolvedRoot, err }, '[workspace] realpath failed for contentDir');
        errorResponse(
          res,
          500,
          'urn:ok:error:internal-server-error',
          'Workspace realpath failed.',
          { handler: 'workspace', detail: code ?? undefined, cause: err },
        );
        return;
      }
    }
    successResponse(
      res,
      200,
      WorkspaceSuccessSchema,
      {
        contentDir: resolvedContentDir,
        pathSeparator: sep,
        symlinkResolved,
      },
      { handler: 'workspace' },
    );
  }

  async function handleInstalledAgentsRoute(
    req: IncomingMessage,
    res: ServerResponse,
  ): Promise<void> {
    if (!checkLocalOpSecurity(req, res, { handler: 'installed-agents' })) return;
    try {
      await handleInstalledAgents(req, res, installedAgentsCache.probeAll);
    } catch (e) {
      if (!res.headersSent) {
        log.error(
          { err: e, requestId: getRequestId(req) },
          '[installed-agents] route wrapper failed',
        );
        errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
          handler: 'installed-agents',
          cause: e,
        });
      }
    }
  }

  const lockDir = projectDir ? getLocalDir(projectDir) : null;
  async function handleApiConfig(req: IncomingMessage, res: ServerResponse): Promise<void> {
    if (req.method === 'GET' || req.method === 'HEAD') {
      try {
        const collabUrl = collabUrlFromRequestHeaders(req.headers);
        const port = lockDir ? (readServerLock(lockDir)?.port ?? 0) : 0;
        const payload = { collabUrl, previewUrl: null, port, singleFile: ephemeral };
        if (req.method === 'HEAD') {
          res.setHeader('Content-Type', 'application/json');
          res.setHeader('Cache-Control', 'no-store');
          res.setHeader('X-Content-Type-Options', 'nosniff');
          res.statusCode = 200;
          res.end();
          return;
        }
        successResponse(res, 200, ApiConfigSuccessSchema, payload, {
          handler: 'api-config',
          extraHeaders: { 'Cache-Control': 'no-store' },
        });
      } catch (e) {
        errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
          handler: 'api-config',
          cause: e,
        });
      }
      return;
    }
    errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
      handler: 'api-config',
      extraHeaders: { Allow: 'GET, HEAD' },
    });
  }

  async function handleConfigDiagnostics(req: IncomingMessage, res: ServerResponse): Promise<void> {
    if (req.method === 'GET' || req.method === 'HEAD') {
      try {
        const payload = getConfigDiagnostics?.() ?? { diagnostics: [] };
        if (req.method === 'HEAD') {
          res.setHeader('Content-Type', 'application/json');
          res.setHeader('Cache-Control', 'no-store');
          res.setHeader('X-Content-Type-Options', 'nosniff');
          res.statusCode = 200;
          res.end();
          return;
        }
        successResponse(res, 200, ConfigDiagnosticsReportSchema, payload, {
          handler: 'api-config-diagnostics',
          extraHeaders: { 'Cache-Control': 'no-store' },
        });
      } catch (e) {
        errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
          handler: 'api-config-diagnostics',
          cause: e,
        });
      }
      return;
    }
    errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
      handler: 'api-config-diagnostics',
      extraHeaders: { Allow: 'GET, HEAD' },
    });
  }

  const handleSemanticStatus = withValidation(
    EmptyRequestSchema,
    async (_req, res) => {
      try {
        let enabled = false;
        let ready = false;
        let capable = false;
        let providerError = false;
        let providerErrorReason: SemanticProviderErrorReason | null = null;
        let embedded = 0;
        if (semanticSearch) {
          const status = semanticSearch.getStatus();
          enabled = status.enabled;
          ready = status.ready;
          capable = status.capable;
          providerError = status.providerError;
          providerErrorReason = status.providerErrorReason;
          embedded = status.embeddedCount;
        }
        const statusConfig = readSemanticProviderConfig?.();
        const statusBaseUrl = statusConfig?.baseUrl ?? DEFAULT_EMBEDDINGS_BASE_URL;
        const cred = await resolveEmbeddingsCredential(
          new FileEmbeddingsBackend(embeddingsSecretsFile),
          projectDir ?? contentDir,
          statusBaseUrl,
        );
        const keyPresent = cred.apiKey !== null;
        const keyNotRequired = !keyPresent && cred.keyless;
        const keySource: 'project' | 'file' | 'env' | null = keyPresent
          ? (cred.source as 'project' | 'file' | 'env')
          : null;
        const keyHint = cred.apiKey && cred.apiKey.length >= 8 ? cred.apiKey.slice(-4) : null;
        let total = 0;
        for (const [docName] of getFileIndex()) {
          if (!isSystemDoc(docName) && !isConfigDoc(docName) && !isHiddenDocName(docName)) {
            total += 1;
          }
        }
        successResponse(
          res,
          200,
          SemanticIndexStatusSchema,
          {
            enabled,
            keyPresent,
            keyNotRequired,
            keySource,
            keyHint,
            ready,
            capable,
            providerError,
            providerErrorReason,
            embedded,
            total,
          },
          { handler: 'semantic-status', extraHeaders: { 'Cache-Control': 'no-store' } },
        );
      } catch (e) {
        errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
          handler: 'semantic-status',
          cause: e,
        });
      }
    },
    { handler: 'semantic-status', method: 'GET', skipBodyParse: true },
  );

  const RESCUE_MAX_AGE_MS = 24 * 60 * 60 * 1000;

  const pruneEmptyRescueAncestors = (filePath: string, rescueDir: string): void => {
    let dir = dirname(filePath);
    while (dir !== rescueDir && dir.startsWith(`${rescueDir}${sep}`)) {
      try {
        tracedRmdirSync(dir);
      } catch (e) {
        log.debug({ err: e }, '[rescue] empty-directory prune stopped (non-critical)');
        return;
      }
      dir = dirname(dir);
    }
  };

  const handleRescueList = withValidation(
    EmptyRequestSchema,
    async (_req, res) => {
      try {
        if (!shadowRef?.current) {
          successResponse(res, 200, RescueListSuccessSchema, [], {
            handler: 'rescue-list',
            extraHeaders: { 'Cache-Control': 'no-store' },
          });
          return;
        }

        const now = Date.now();
        const entries: (RescueEntryFlat | (RescueEntryTimeline & TimelineRescueEntry))[] = [];

        const rescueDir = resolve(shadowRef.current.gitDir, 'rescue');
        if (existsSync(rescueDir)) {
          try {
            const files = readdirSync(rescueDir, { encoding: 'utf-8', recursive: true })
              .map((entry) => entry.replaceAll(sep, '/'))
              .filter((f) => isSupportedDocFile(f));
            const canonicalRescueDir = realpathSync(rescueDir);
            for (const file of files) {
              const filePath = resolve(rescueDir, file);
              let canonical: string;
              try {
                canonical = realpathSync(filePath);
              } catch (e) {
                log.warn({ file, err: e }, '[rescue] skipping unresolvable rescue entry');
                continue;
              }
              if (!isWithinDir(canonical, canonicalRescueDir)) {
                log.warn(
                  { file, canonical },
                  '[rescue] skipping rescue entry resolving outside the rescue directory',
                );
                continue;
              }
              try {
                const stat = statSync(canonical);
                if (!stat.isFile()) continue;
                const age = now - stat.mtimeMs;

                if (age > RESCUE_MAX_AGE_MS) {
                  try {
                    tracedUnlinkSync(canonical);
                    pruneEmptyRescueAncestors(canonical, canonicalRescueDir);
                  } catch (e) {
                    log.debug({ err: e }, '[rescue] cleanup failed (non-critical)');
                  }
                  continue;
                }

                entries.push({
                  docName: stripDocExtension(file),
                  timestamp: stat.mtime.toISOString(),
                  size: stat.size,
                  source: 'flat',
                });
              } catch (e) {
                log.warn({ file, err: e }, '[rescue] skipping uninspectable rescue entry');
              }
            }
          } catch (err) {
            log.error({ err }, '[rescue] Failed to list flat-file rescue buffers');
          }
        }

        try {
          const branch = getCurrentBranch?.() ?? 'main';
          const timelineEntries = await listRescueCheckpoints(shadowRef.current, branch);
          for (const t of timelineEntries) {
            entries.push({ ...t, source: 'timeline' });
          }
        } catch (err) {
          log.error({ err }, '[rescue] Failed to list timeline-ref rescue checkpoints');
        }

        successResponse(res, 200, RescueListSuccessSchema, entries, {
          handler: 'rescue-list',
          extraHeaders: { 'Cache-Control': 'no-store' },
        });
      } catch (e) {
        errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
          handler: 'rescue-list',
          cause: e,
        });
      }
    },
    { handler: 'rescue-list', method: 'GET', skipBodyParse: true },
  );

  const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {
    '/api/config': handleApiConfig,
    '/api/config/diagnostics': handleConfigDiagnostics,
    '/api/server-info': handleServerInfo,
    '/api/principal': handlePrincipal,
    '/api/workspace': handleWorkspace,
    '/api/semantic-status': handleSemanticStatus,
    '/api/acp/catalog': handleAcpCatalog,
    '/api/acp/models': handleAcpModels,
    '/api/installed-agents': handleInstalledAgentsRoute,
    '/api/__embed-detect': handleEmbedDetect,
    '/api/rescue': handleRescueList,
  };

  const table: ApiRouteTable = {
    resolve(url) {
      const handler = routes[url];
      if (handler) {
        return { template: url, dispatch: (req, res) => handler(req, res) };
      }
      return null;
    },
    isMutating: () => false,
  };

  return {
    paths: Object.keys(routes),
    table,
  };
}