dsh-model-pool 0.0.0-stage → 0.1.0

package/index.js

@@ -0,0 +1,718 @@
+/**
+ * dsh-model-pool — Host half.
+ *
+ * Registers one virtual provider route whose models are the union of every
+ * registered provider's models, then intercepts the `llm/stream` waterfall for
+ * that route and dispatches each call to a concrete provider chosen by the
+ * configured strategy.
+ *
+ * Mechanism evidence and the full design live in `docs/CONTRACT.md`.
+ *
+ * @module dsh-model-pool
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { PoolAdapter } from './lib/adapter.js';
+import { readPoolSnapshot } from './lib/catalog.js';
+import { HealthRegistry } from './lib/health.js';
+import { HolidayCalendar, mergeOverride } from './lib/holiday-calendar.js';
+import { Router } from './lib/router.js';
+import {
+  DEFAULT_PEAK_TIME_ZONE,
+  DEFAULT_PEAK_WEEKDAYS,
+  DEFAULT_PEAK_WINDOWS,
+  describePeriod,
+  wallClock,
+} from './lib/peak.js';
+import { STRATEGIES } from './lib/strategies.js';
+
+/** HTTP prefix the browser half reads its state from. */
+const API_PREFIX = '/api/model-pool';
+
+/**
+ * Pool configuration. Every editable field is volatile: Settings writes reach
+ * the running refs through the Loader without remounting the plugin
+ * (`cordis-plugin-loader/lib/index.js:391-425`).
+ */
+export const Config = z.object({
+  providerId: z
+    .string()
+    .default('model-pool')
+    .description('Route id of the virtual pool provider. Changing it needs a restart to re-register the route.'),
+  providerName: z
+    .string()
+    .default('Model Pool')
+    .description('Display name of the virtual pool provider in the model picker.'),
+  strategy: z
+    .union([...STRATEGIES])
+    .default('priority')
+    .volatile()
+    .description('How one pooled call picks its concrete provider.'),
+  fallback: z
+    .boolean()
+    .default(true)
+    .volatile()
+    .description('Try the next candidate when an attempt fails before producing any output.'),
+  skipUnavailable: z
+    .boolean()
+    .default(true)
+    .volatile()
+    .description('Skip routes that are cooling down after a failure.'),
+  cooldownMs: z
+    .natural()
+    .default(60000)
+    .volatile()
+    .description('How long a failed route stays out of rotation, in milliseconds.'),
+  maxAttempts: z
+    .natural()
+    .default(3)
+    .volatile()
+    .description('Upper bound on concrete providers tried for one call.'),
+  sticky: z
+    .boolean()
+    .default(true)
+    .volatile()
+    .description(
+      'Keep one session on the route it already used instead of re-deciding every '
+        + 'turn. A new session (or a re-selected model) picks again with the strategy. '
+        + 'Keeps the provider prompt cache warm; failover still applies when the route fails.',
+    ),
+  include: z
+    .array(z.string())
+    .default([])
+    .volatile()
+    .description('Provider allowlist. Empty means every registered provider.'),
+  exclude: z
+    .array(z.string())
+    .default([])
+    .volatile()
+    .description('Provider denylist, applied after the allowlist.'),
+  excludeModels: z
+    .array(z.string())
+    .default([])
+    .volatile()
+    .description('Model ids or id substrings to keep out of the pool.'),
+  providerOrder: z
+    .array(z.string())
+    .default([])
+    .volatile()
+    .description('Provider ids from highest to lowest priority, used by the priority strategy.'),
+  peakEnabled: z
+    .boolean()
+    .default(true)
+    .volatile()
+    .description('Rank providers differently during peak and idle periods.'),
+  peakTimeZone: z
+    .string()
+    .default(DEFAULT_PEAK_TIME_ZONE)
+    .volatile()
+    .description('Time zone the peak windows are expressed in. Defaults to Beijing time.'),
+  peakWindows: z
+    .array(z.string())
+    .default([...DEFAULT_PEAK_WINDOWS])
+    .volatile()
+    .description(
+      'Peak windows as "HH:MM-HH:MM" in the configured time zone. Everything outside them '
+        + 'is idle. An empty list means the peak period never occurs.',
+    ),
+  peakWeekdays: z
+    .array(z.number())
+    .default([...DEFAULT_PEAK_WEEKDAYS])
+    .volatile()
+    .description('ISO weekdays (1 = Monday … 7 = Sunday) whose windows are peak. An empty list means never.'),
+  holidaySync: z
+    .boolean()
+    .default(true)
+    .volatile()
+    .description(
+      'Fetch the statutory holiday calendar automatically. The dates are data, not a setting: '
+        + 'a maintained dataset is downloaded and cached, so nobody types holiday dates by hand.',
+    ),
+  holidaySource: z
+    .string()
+    .default('holiday-cn')
+    .volatile()
+    .description(
+      'Calendar source id, or "off" to keep the fetched dates out of routing entirely. '
+        + 'The default (holiday-cn) is NateScarlet\'s dataset generated from the State Council notices.',
+    ),
+  holidayUrlTemplate: z
+    .string()
+    .default('')
+    .volatile()
+    .description(
+      'Custom URL template containing "{year}" for the per-year JSON document. Empty uses the '
+        + 'source default, which tries jsDelivr first and raw.githubusercontent second.',
+    ),
+  holidayCacheDays: z
+    .natural()
+    .default(30)
+    .volatile()
+    .description('Age in days after which the cached calendar is refetched. Routing always reads the cache.'),
+  holidayUpdateDays: z
+    .natural()
+    .default(7)
+    .volatile()
+    .description('Background refresh cadence in days. Zero or a failed refresh never affects routing.'),
+  holidayOverride: z
+    .array(z.string())
+    .default([])
+    .volatile()
+    .description(
+      'Manual dates ("YYYY-MM-DD") layered on top of the fetched calendar for one-off corrections. '
+        + 'A date listed here survives every background refresh.',
+    ),
+  peakMakeupWorkdays: z
+    .array(z.string())
+    .default([])
+    .volatile()
+    .description(
+      'Extra dates ("YYYY-MM-DD") that count as working days even on a weekend, on top of the '
+        + '调休上班日 the fetched calendar already reports. Normally empty: use it only for a day '
+        + 'the State Council notice does not cover.',
+    ),
+  peakProviderOrder: z
+    .array(z.string())
+    .default([])
+    .volatile()
+    .description('Provider ranking used during the peak period. Empty inherits providerOrder.'),
+  offPeakProviderOrder: z
+    .array(z.string())
+    .default([])
+    .volatile()
+    .description('Provider ranking used during the idle period. Empty inherits providerOrder.'),
+  weights: z
+    .dict(z.natural())
+    .default({})
+    .volatile()
+    .description('Per-provider weights for the weighted-random strategy. Missing providers count as 1.'),
+  costs: z
+    .dict(z.number())
+    .default({})
+    .volatile()
+    .description('Per-provider relative cost hints for the cheapest strategy. Missing providers count as 0.'),
+  modelGroups: z
+    .array(
+      z.object({
+        id: z.string().default(''),
+        name: z.string(),
+        models: z.array(z.string()).default([]),
+        merge: z.boolean().default(true),
+        strategy: z.string().default(''),
+      }),
+    )
+    .default([
+      {
+        id: 'deepseek-v4.1-flash',
+        name: 'DeepSeek V4.1 Flash',
+        models: ['deepseek-v4.1-flash*', 'deepseek-flash'],
+        merge: true,
+        strategy: '',
+      },
+      {
+        id: 'glm-5.3-flash',
+        name: 'GLM 5.3 Flash',
+        models: ['glm-5.3-flash*'],
+        merge: true,
+        strategy: '',
+      },
+    ])
+    .volatile()
+    .description(
+      'Named groups that merge the same model served under different provider ids into one pool row. '
+        + 'Each entry lists selectors matched against the concrete id, the "provider/model" pair, or the '
+        + 'normalized id; "*" and "?" wildcards are allowed. merge: true (the default) removes the claimed '
+        + 'routes from their single-id pools so only one row remains; merge: false adds an extra curated pool '
+        + 'and leaves the natural rows in place.',
+    ),
+});
+
+/** The pool needs the model registry; every other dependency is optional. */
+export const inject = ['llm'];
+
+/**
+ * Read a volatile ref, falling back to a plain value.
+ * @param {object|unknown} field - a schemastery field value.
+ * @param {unknown} fallback - value when the field is absent.
+ * @returns {unknown} the current value.
+ */
+function read(field, fallback) {
+  if (field !== null && typeof field === 'object' && typeof field.get === 'function') {
+    const value = field.get();
+    return value === undefined ? fallback : value;
+  }
+  return field === undefined ? fallback : field;
+}
+
+/**
+ * The directory the plugin keeps its own data in.
+ *
+ * `DSH_HOME` is honoured so a portable install keeps the cache beside the rest of its
+ * state; without it the documented default applies. The calendar cache lives here.
+ *
+ * @returns {string} absolute data directory.
+ */
+function dataDir() {
+  const home = typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME.trim() !== ''
+    ? process.env.DSH_HOME.trim()
+    : join(homedir(), '.dsh');
+  return join(home, 'model-pool');
+}
+
+/**
+ * Read the holiday source settings as the pair the calendar understands.
+ *
+ * `holidaySource` is documented as a source id, the literal `off`, or a full URL. A URL
+ * is handed to the calendar as its template: an arbitrary host has no source id, and
+ * silently fetching nothing would look like an empty calendar instead of a misconfiguration.
+ *
+ * @param {object} config - resolved Config.
+ * @returns {{ enabled: boolean, source: string, urlTemplate: string }} the source settings.
+ */
+function calendarSource(config) {
+  const raw = String(read(config.holidaySource, 'holiday-cn')).trim();
+  const template = String(read(config.holidayUrlTemplate, '') ?? '').trim();
+  const enabled = read(config.holidaySync, true) !== false;
+  if (!enabled || raw === 'off' || raw === '') {
+    return { enabled: false, source: 'holiday-cn', urlTemplate: template };
+  }
+  // A URL is both the source id and its own template: keeping it as the id makes
+  // `/state.calendar.source` name the host the dates actually came from.
+  if (/^https?:\/\//i.test(raw)) return { enabled: true, source: raw, urlTemplate: raw };
+  return { enabled: true, source: raw, urlTemplate: template };
+}
+
+/**
+ * The date sets routing should use, resolved once per config read.
+ *
+ * The fetched calendar is merged with `holidayOverride`, which is applied through
+ * `mergeOverride` so a manual correction can move a date between the two sets instead of
+ * leaving it in both (where the holiday-wins precedence rule would quietly beat the
+ * operator). The manual `peakMakeupWorkdays` list is unioned on top as the documented
+ * opt-in escape hatch. Reading the sets here — not per candidate — keeps a routing
+ * decision to one lookup and never touches the network.
+ *
+ * @param {object} config - resolved Config.
+ * @param {{ enabled: boolean, source: string, urlTemplate: string }} source - source settings.
+ * @param {import('./lib/holiday-calendar.js').HolidayCalendar} calendar - the live calendar.
+ * @returns {{ holidays: string[], makeupWorkdays: string[] }} resolved date sets.
+ */
+function holidaySets(config, source, calendar) {
+  const override = [...(read(config.holidayOverride, []) ?? [])];
+  const manual = [...(read(config.peakMakeupWorkdays, []) ?? [])];
+  if (!source.enabled) return { holidays: override, makeupWorkdays: manual };
+  const merged = mergeOverride(
+    { holidays: [...calendar.holidays()], makeupWorkdays: [...calendar.makeupWorkdays()] },
+    { holidays: override },
+  );
+  const makeup = new Set(merged.makeupWorkdays);
+  for (const date of manual) makeup.add(date);
+  return { holidays: merged.holidays, makeupWorkdays: [...makeup].sort() };
+}
+
+/**
+ * Snapshot the volatile config into a plain object the pure modules accept.
+ * @param {object} config - resolved Config.
+ * @param {{ holidays: string[], makeupWorkdays: string[] }} sets - resolved holiday date sets.
+ * @returns {object} plain pool configuration.
+ */
+function plainConfig(config, sets = { holidays: [], makeupWorkdays: [] }) {
+  return {
+    providerId: String(read(config.providerId, 'model-pool')),
+    providerName: String(read(config.providerName, 'Model Pool')),
+    strategy: String(read(config.strategy, 'priority')),
+    fallback: read(config.fallback, true) !== false,
+    skipUnavailable: read(config.skipUnavailable, true) !== false,
+    cooldownMs: Number(read(config.cooldownMs, 60000)) || 60000,
+    maxAttempts: Math.max(1, Number(read(config.maxAttempts, 3)) || 3),
+    sticky: read(config.sticky, true) !== false,
+    include: [...(read(config.include, []) ?? [])],
+    exclude: [...(read(config.exclude, []) ?? [])],
+    excludeModels: [...(read(config.excludeModels, []) ?? [])],
+    providerOrder: [...(read(config.providerOrder, []) ?? [])],
+    peakEnabled: read(config.peakEnabled, true) !== false,
+    peakTimeZone: String(read(config.peakTimeZone, DEFAULT_PEAK_TIME_ZONE)),
+    peakWindows: [...(read(config.peakWindows, DEFAULT_PEAK_WINDOWS) ?? [])],
+    peakWeekdays: [...(read(config.peakWeekdays, DEFAULT_PEAK_WEEKDAYS) ?? [])],
+    // Resolved date sets, not raw config: `peak.js` has no built-in holiday table.
+    holidays: sets.holidays,
+    makeupWorkdays: sets.makeupWorkdays,
+    peakMakeupWorkdays: [...(read(config.peakMakeupWorkdays, []) ?? [])],
+    peakProviderOrder: [...(read(config.peakProviderOrder, []) ?? [])],
+    offPeakProviderOrder: [...(read(config.offPeakProviderOrder, []) ?? [])],
+    holidaySync: read(config.holidaySync, true) !== false,
+    holidaySource: String(read(config.holidaySource, 'holiday-cn')),
+    holidayUrlTemplate: String(read(config.holidayUrlTemplate, '') ?? ''),
+    holidayCacheDays: Math.max(0, Number(read(config.holidayCacheDays, 30)) || 0),
+    holidayUpdateDays: Math.max(0, Number(read(config.holidayUpdateDays, 7)) || 0),
+    holidayOverride: [...(read(config.holidayOverride, []) ?? [])],
+    weights: { ...(read(config.weights, {}) ?? {}) },
+    costs: { ...(read(config.costs, {}) ?? {}) },
+    modelGroups: [...(read(config.modelGroups, []) ?? [])],
+  };
+}
+
+/**
+ * Whether a request is a pooled call this plugin must handle.
+ * @param {object} options - a `GenerateOptions` at the waterfall.
+ * @param {string} providerId - the virtual route.
+ * @returns {boolean} true when the request names the pool route.
+ */
+function isPooled(options, providerId) {
+  return options !== null
+    && typeof options === 'object'
+    && options.provider === providerId
+    && typeof options.model === 'string'
+    && options.model.length > 0;
+}
+
+/**
+ * Write one JSON response.
+ * @param {import('node:http').ServerResponse} res - the response.
+ * @param {number} status - HTTP status code.
+ * @param {unknown} body - JSON-serializable body.
+ */
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+/**
+ * Read and discard a request body so the socket can be reused.
+ * @param {import('node:http').IncomingMessage} req - the request.
+ * @returns {Promise<void>} settles once the body is drained.
+ */
+async function drain(req) {
+  if (req.readableEnded === true) return;
+  for await (const _chunk of req) {
+    // Drained only; the API takes no request bodies.
+  }
+}
+
+/**
+ * Mount the pool route, its routing listener, and the settings API.
+ * @param {object} ctx - plugin context.
+ * @param {object} config - resolved Config.
+ */
+export function apply(ctx, config) {
+  const health = new HealthRegistry();
+  /** Latest successful pool snapshot; `null` until the first successful read. */
+  let snapshot = { providerId: '', providerName: '', models: [], failures: [], takenAt: 0 };
+  /** Serializes refreshes so concurrent reads cannot interleave. */
+  let refreshing;
+
+  // One calendar for the process. Routing reads its in-memory sets, so a routing
+  // decision never waits on the network; `refresh()` is the only code that does I/O.
+  const initialSource = calendarSource(config);
+  const calendar = new HolidayCalendar({
+    dir: dataDir(),
+    source: initialSource.source,
+    urlTemplate: initialSource.urlTemplate,
+    logger: ctx.logger,
+  });
+
+  /**
+   * Re-resolve the calendar against the live config, then refresh it.
+   *
+   * `reconfigure` runs first on every cycle so a Settings edit to `holidaySource` or
+   * `holidayUrlTemplate` takes effect without a restart. `refresh()` never throws and
+   * never rejects: a failure leaves the previous cache in place.
+   *
+   * @param {{ force?: boolean, reason?: string }} options - refresh controls.
+   * @returns {Promise<object>} the calendar status after the attempt.
+   */
+  function syncCalendar({ force = false, reason = 'scheduled' } = {}) {
+    const cfg = currentConfig();
+    const source = calendarSource(config);
+    if (!source.enabled) {
+      // Syncing is off: nothing is fetched, and `holidaySets` already refuses to read
+      // the calendar. The loaded years are deliberately left alone so a later
+      // re-enable starts warm instead of cold.
+      return Promise.resolve(calendarStatus());
+    }
+    calendar.reconfigure({ source: source.source, urlTemplate: source.urlTemplate });
+    return calendar.refresh({ force, cacheDays: cfg.holidayCacheDays }).then((status) => {
+      ctx.logger?.debug?.(
+        'model-pool: holiday calendar %s (%s): years=%s holidays=%s error=%s',
+        reason,
+        status.source,
+        status.years.join(','),
+        status.holidayCount,
+        status.lastError ?? 'none',
+      );
+      return status;
+    });
+  }
+
+  /**
+   * The calendar year the peak policy is currently in.
+   *
+   * Read from the CONFIGURED zone, not the host's: the policy judges days in
+   * `peakTimeZone`, so a host west of UTC on 1 January would otherwise report the
+   * previous year and show last year's holiday figures for a day the policy already
+   * treats as the new one.
+   *
+   * @param {object} cfg - plain pool configuration.
+   * @returns {number} the four-digit calendar year.
+   */
+  function policyYear(cfg) {
+    return Number(wallClock(Date.now(), cfg.peakTimeZone).date.slice(0, 4));
+  }
+
+  /**
+   * The calendar facts the Settings page renders.
+   *
+   * When syncing is off the loaded years are irrelevant to routing, so reporting them
+   * as a live calendar would be a lie the card then repeats. The inert status says
+   * plainly that nothing is in play — but it keeps the same shape, so the page never
+   * has to branch on which state it received.
+   *
+   * @returns {object} the calendar status for `/state`.
+   */
+  function calendarStatus() {
+    const cfg = currentConfig();
+    const year = policyYear(cfg);
+    if (!calendarSource(config).enabled) {
+      return {
+        years: [],
+        pendingYears: [],
+        fetchedAt: null,
+        source: 'off',
+        stale: true,
+        lastError: null,
+        holidayCount: 0,
+        makeupCount: 0,
+        papers: [],
+        currentYear: year,
+        currentHolidayCount: 0,
+        currentMakeupCount: 0,
+      };
+    }
+    return calendar.status({ cacheDays: cfg.holidayCacheDays, year });
+  }
+
+  const currentConfig = () => {
+    const source = calendarSource(config);
+    return plainConfig(config, holidaySets(config, source, calendar));
+  };
+  const currentSnapshot = () => snapshot;
+
+  /**
+   * Re-read the live registry into the pool snapshot.
+   * @param {string} reason - why the refresh ran, for the log line.
+   * @returns {Promise<object>} the snapshot in use.
+   */
+  async function refresh(reason) {
+    if (refreshing !== undefined) return refreshing;
+    const cfg = currentConfig();
+    refreshing = (async () => {
+      try {
+        const { snapshot: next } = await readPoolSnapshot(ctx.llm, cfg, cfg.providerId);
+        snapshot = next;
+        return snapshot;
+      } catch (error) {
+        ctx.logger?.warn?.('model-pool: catalog refresh failed (%s): %s', reason, error?.message ?? String(error));
+        return snapshot;
+      } finally {
+        refreshing = undefined;
+      }
+    })();
+    return refreshing;
+  }
+
+  const router = new Router({
+    llm: ctx.llm,
+    config: currentConfig,
+    snapshot: currentSnapshot,
+    health,
+    logger: ctx.logger,
+  });
+
+  // ── the virtual provider route ────────────────────────────────────────────
+  const initial = currentConfig();
+  const adapter = new PoolAdapter(currentSnapshot, initial.providerId, initial.providerName);
+
+  ctx.effect(() => {
+    const registration = ctx.llm.registerAdapter([initial.providerId], adapter);
+    // Fill the catalog before the picker can ask for it; a failure here only
+    // means the first menu open shows an empty pool until the refresh lands.
+    void refresh('registration');
+    // The provider topology changed: pools may have gained or lost models.
+    const off = ctx.on('llm/adapters-updated', () => {
+      void refresh('adapters-updated');
+    });
+    return () => {
+      off();
+      registration();
+    };
+  }, 'model-pool: virtual provider route');
+
+  // ── holiday calendar ──────────────────────────────────────────────────────
+  ctx.effect(() => {
+    // Warm the calendar before the first routing decision can need it. The request
+    // runs in the background: a cold start must not delay the plugin, and a failure
+    // only means the weekday rule applies until the cache or the network answers.
+    void syncCalendar({ reason: 'mount' });
+    // The cadence is re-read every cycle rather than captured, because every config
+    // field is volatile: settings edited in the page must take effect without a
+    // remount. The floor of one day keeps a `0` from becoming a hot loop, and `unref`
+    // keeps a pending timer from holding the process open on shutdown.
+    let timer;
+    let disposed = false;
+    const schedule = () => {
+      const days = Math.max(currentConfig().holidayUpdateDays, 1);
+      timer = setTimeout(() => {
+        void syncCalendar({ reason: 'interval' });
+        if (!disposed) schedule();
+      }, days * 86_400_000);
+      timer.unref?.();
+    };
+    schedule();
+    return () => {
+      disposed = true;
+      clearTimeout(timer);
+    };
+  }, 'model-pool: holiday calendar');
+
+  // ── routing ───────────────────────────────────────────────────────────────
+  ctx.on('llm/stream', (options, next) => {
+    const cfg = currentConfig();
+    if (!isPooled(options, cfg.providerId)) return next();
+    return router.route(options);
+  });
+
+  // ── settings API ──────────────────────────────────────────────────────────
+  ctx.inject(['webServer'], (scoped) => {
+    /**
+     * Current state payload for the Settings page.
+     * @returns {object} JSON-serializable state.
+     */
+    const state = () => {
+      const cfg = currentConfig();
+      return {
+        snapshot,
+        health: { entries: health.entries() },
+        config: {
+          providerId: cfg.providerId,
+          providerName: cfg.providerName,
+          strategy: cfg.strategy,
+          fallback: cfg.fallback,
+          skipUnavailable: cfg.skipUnavailable,
+          cooldownMs: cfg.cooldownMs,
+          maxAttempts: cfg.maxAttempts,
+          sticky: cfg.sticky,
+          include: cfg.include,
+          exclude: cfg.exclude,
+          excludeModels: cfg.excludeModels,
+          providerOrder: cfg.providerOrder,
+          peakEnabled: cfg.peakEnabled,
+          peakTimeZone: cfg.peakTimeZone,
+          peakWindows: cfg.peakWindows,
+          peakWeekdays: cfg.peakWeekdays,
+          peakMakeupWorkdays: cfg.peakMakeupWorkdays,
+          peakProviderOrder: cfg.peakProviderOrder,
+          offPeakProviderOrder: cfg.offPeakProviderOrder,
+          holidaySync: cfg.holidaySync,
+          holidaySource: cfg.holidaySource,
+          holidayUrlTemplate: cfg.holidayUrlTemplate,
+          holidayCacheDays: cfg.holidayCacheDays,
+          holidayUpdateDays: cfg.holidayUpdateDays,
+          holidayOverride: cfg.holidayOverride,
+          weights: cfg.weights,
+          costs: cfg.costs,
+          modelGroups: cfg.modelGroups,
+        },
+        // The live peak/idle reading, including when it next flips. The Settings
+        // card renders this so the policy is visible instead of implied.
+        period: describePeriod(Date.now(), cfg),
+        // What the holiday calendar currently knows. The dates are fetched, so the
+        // page reports the state of the fetch (years, freshness, last error) instead
+        // of offering a list to edit — nobody maintains holiday dates by hand.
+        calendar: calendarStatus(),
+        recent: router.recent,
+        // Diagnostic: the raw `reasoningEffort` the runtime handed the pool for
+        // the latest call. It makes a mapped tier explainable instead of a guess.
+        lastInbound: router.lastInbound ?? null,
+        sessions: router.sessionEntries(),
+        version: VERSION,
+      };
+    };
+
+    /**
+     * One prefix route serving the whole API.
+     * @param {import('node:http').IncomingMessage} req - request.
+     * @param {import('node:http').ServerResponse} res - response.
+     * @returns {Promise<void>} settles after the response is written.
+     */
+    const handler = async (req, res) => {
+      try {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const path = url.pathname.slice(API_PREFIX.length).replace(/\/+$/, '');
+        const method = req.method ?? 'GET';
+
+        if (method === 'GET' && (path === '/state' || path === '')) {
+          await drain(req);
+          sendJson(res, 200, state());
+          return;
+        }
+        // One session's last route. The composer dock polls this: it is a few
+        // hundred bytes, while `/state` carries the whole catalog.
+        if (method === 'GET' && path === '/session') {
+          await drain(req);
+          const sessionId = url.searchParams.get('id') ?? '';
+          const entry = router.sessionOf(sessionId);
+          if (entry === undefined) {
+            sendJson(res, 200, { sessionId, route: null });
+            return;
+          }
+          sendJson(res, 200, { sessionId, route: entry });
+          return;
+        }
+        if (method === 'POST' && path === '/refresh') {
+          await drain(req);
+          await refresh('settings');
+          sendJson(res, 200, state());
+          return;
+        }
+        if (method === 'POST' && path === '/reset-health') {
+          await drain(req);
+          health.reset();
+          sendJson(res, 200, state());
+          return;
+        }
+        // The Settings card's "sync now". `force` is deliberate: the operator asked,
+        // so a fresh cache must not swallow the request. The response is written after
+        // the attempt either way, because `syncCalendar` cannot reject.
+        if (method === 'POST' && path === '/refresh-calendar') {
+          await drain(req);
+          await syncCalendar({ force: true, reason: 'settings' });
+          sendJson(res, 200, state());
+          return;
+        }
+        await drain(req);
+        sendJson(res, 404, { error: { message: `unknown model-pool endpoint ${method} ${path}` } });
+      } catch (error) {
+        if (res.headersSent !== true) {
+          sendJson(res, 500, { error: { message: error instanceof Error ? error.message : String(error) } });
+        } else {
+          res.end();
+        }
+      }
+    };
+
+    scoped.effect(
+      () => scoped.webServer.register({ kind: 'prefix', path: API_PREFIX, handler }),
+      'model-pool: settings API',
+    );
+  });
+}
+
+/** Package version, reported by the settings API. */
+const VERSION = '0.1.0';