@fonlan/dsh-model-parameters 0.1.0

package/src/server/rpc.ts

@@ -0,0 +1,162 @@
+/**
+ * Fenced JSON API under /plugins/@fonlan/dsh-model-parameters/api/<method> for
+ * the web settings page. Same browser-trust fence as the /api gateway and the
+ * model-router plugin: loopback Host-header or configured trustedHosts,
+ * same-origin browser markers.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type { ModelParametersService } from './service.js'
+
+const API_PREFIX = '/plugins/@fonlan/dsh-model-parameters/api'
+
+// ── browser-trust fence (mirrors dsh-client-connection's api-request-trust) ──
+
+function header(headers: IncomingMessage['headers'], name: string): string | undefined {
+  const value = headers[name]
+  return typeof value === 'string' ? value : undefined
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  const parts = hostname.split('.')
+  return parts.length === 4 && parts[0] === '127' && parts.every(p => /^\d{1,3}$/.test(p) && Number(p) <= 255)
+}
+
+function isTrustedApiRequest(req: IncomingMessage, trustedHosts: readonly string[]): boolean {
+  const host = header(req.headers, 'host')
+  if (host === undefined) return false
+  let hostUrl: URL
+  try {
+    hostUrl = new URL(`http://${host}`)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHostname(hostUrl.hostname) && !trustedHosts.includes(hostUrl.host) && !trustedHosts.includes(hostUrl.hostname)) {
+    return false
+  }
+  if (header(req.headers, 'sec-fetch-site') === 'cross-site') return false
+  const origin = header(req.headers, 'origin')
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}
+
+function trustedHostsOf(ctx: Context): string[] {
+  for (const entry of ctx.get('loader')?.entries?.() ?? []) {
+    if (entry.options?.name === 'connection') {
+      const config = entry.options.config as { trustedHosts?: string[] } | undefined
+      return config?.trustedHosts ?? []
+    }
+  }
+  return []
+}
+
+// ── wire helpers ────────────────────────────────────────────────────────────
+
+function writeJson(res: ServerResponse, body: unknown): void {
+  res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify(body))
+}
+
+function writeError(res: ServerResponse, code: string, message: string, status = 400): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify({ ok: false, error: { code, message } }))
+}
+
+async function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = []
+  for await (const chunk of req) chunks.push(chunk as Buffer)
+  const raw = Buffer.concat(chunks).toString('utf8')
+  if (raw.trim() === '') return {}
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : {}
+  } catch {
+    return {}
+  }
+}
+
+function requireString(value: unknown, name: string): string {
+  if (typeof value !== 'string' || value.length === 0) throw new Error(`${name} must be a non-empty string`)
+  return value
+}
+
+// ── routes ──────────────────────────────────────────────────────────────────
+
+export function registerApiRoutes(ctx: Context, service: ModelParametersService): () => void {
+  const fence = (req: IncomingMessage): boolean => isTrustedApiRequest(req, trustedHostsOf(ctx))
+  const disposers: Array<() => void> = []
+
+  const route = (name: string, handler: (payload: Record<string, unknown>) => Promise<unknown>): void => {
+    disposers.push(ctx.webServer.register({
+      kind: 'prefix',
+      path: `${API_PREFIX}/${name}`,
+      handler: async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+        if (!fence(req)) {
+          writeError(res, 'forbidden', 'forbidden', 403)
+          return
+        }
+        if (req.method !== 'POST' && req.method !== 'GET') {
+          writeError(res, 'method', 'method not allowed', 405)
+          return
+        }
+        const payload = await readJsonBody(req)
+        try {
+          const value = await handler(payload)
+          writeJson(res, { ok: true, value })
+        } catch (error) {
+          writeError(res, 'error', error instanceof Error ? error.message : String(error))
+        }
+      },
+    }))
+  }
+
+  route('state', async () => stateOf(service))
+
+  route('refresh', async () => {
+    await service.refreshAndReconcile()
+    return stateOf(service)
+  })
+
+  route('reconcile', async () => {
+    await service.reconcile()
+    return stateOf(service)
+  })
+
+  route('set-config', async (payload) => {
+    const patch = payload.patch
+    if (typeof patch !== 'object' || patch === null) throw new Error('patch must be an object')
+    await service.updateConfig(patch as never)
+    return stateOf(service)
+  })
+
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}
+
+/**
+ * The settings-page view. Deliberately ships only catalog COUNTS — the full
+ * entries array (thousands of models) must never cross the wire or render.
+ */
+function stateOf(service: ModelParametersService): unknown {
+  const config = service.config()
+  const snapshot = service.catalogSnapshot()
+  return {
+    config,
+    catalog: {
+      entries: snapshot.entries.length,
+      providers: snapshot.providers,
+      fetchedAt: snapshot.fetchedAt,
+      fresh: snapshot.fetchedAt > 0
+        && Date.now() - snapshot.fetchedAt < config.ttlDays * 24 * 60 * 60 * 1000,
+      ttlDays: config.ttlDays,
+    },
+    report: service.report(),
+  }
+}

package/src/server/service.ts

@@ -0,0 +1,258 @@
+/**
+ * The model-parameters service: owns the plugin settings namespace, watches
+ * the `llm-pi-ai` namespace for provider model writes, reconciles missing
+ * fields from the cached models.dev catalog, and tracks a fill report.
+ *
+ * Trigger model:
+ *  - any committed `llm-pi-ai` settings change (settings UI apply, manual
+ *    settings.yaml edit published by the file provider, model-router-style
+ *    external writes) runs a reconcile;
+ *  - plugin start runs a backfill reconcile over the existing configuration.
+ * Reconcile is fill-only: it never overwrites a present field, and it writes
+ * nothing when nothing is missing — so its own writes cannot re-trigger a
+ * second patch (the next event sees the fields present and produces no ops).
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import {
+  settingsNamespace,
+  type SettingsScope,
+  type SettingsPathOp,
+} from '@deepseek-ai/dsh-settings'
+import type { PiAiModelProfile } from '@deepseek-ai/dsh-llm-pi-ai'
+import {
+  Config,
+  DEFAULT_CONFIG,
+  PLUGIN_NS,
+  TARGET_NS,
+  type ModelParametersConfig,
+} from '../shared/config.js'
+import {
+  CatalogManager,
+  acceptedInputModalities,
+  identityReasoningEfforts,
+  type CatalogEntry,
+  type CatalogSnapshot,
+} from './catalog.js'
+
+const TARGET = settingsNamespace(TARGET_NS)
+const OWN = settingsNamespace(PLUGIN_NS)
+
+/** One reconcile run's outcome, surfaced to the settings page. */
+export interface FillReport {
+  at: number
+  /** Number of individual field fills applied. */
+  filled: number
+  /** Number of providers whose models array was rewritten. */
+  touched: number
+  /** Model ids (provider/model) that matched nothing in the catalog. */
+  unmatched: string[]
+}
+
+export class ModelParametersService {
+  /**
+   * The settings service value captured from the inject callback. The plugin
+   * itself declares `inject: []` (settings is optional — headless profiles
+   * have no settings service), so `this.ctx.settings` is never resolvable:
+   * the context proxy only walks ancestor fibers, and the provider lives on
+   * a sibling fiber. The injected child ctx itself is only valid while its
+   * fiber is active — the provider can be reloaded (and every dependent
+   * fiber torn down) while an async reconcile is in flight — so all reads
+   * and writes go through the captured service value, which is a plain
+   * object and never walks the fiber chain.
+   */
+  private settings: Context['settings'] | undefined
+  private scope: SettingsScope<ModelParametersConfig> | undefined
+  private lastReport: FillReport | null = null
+  private readonly catalog: CatalogManager
+  private reconciling: Promise<void> | null = null
+
+  constructor(private readonly ctx: Context) {
+    this.catalog = new CatalogManager(ctx.logger)
+  }
+
+  start(): void {
+    // Own settings namespace (config toggles, TTL, provider map). The inject
+    // callback fires asynchronously once the settings service is available, so
+    // the first-run backfill reconcile lives INSIDE it — reconcile needs the
+    // settings service (to read the target namespace and persist fills).
+    this.ctx.inject(['settings'], (sctx) => {
+      this.settings = sctx.settings
+      this.scope = this.settings.register(OWN, Config) as SettingsScope<ModelParametersConfig>
+      // First-run backfill: ensure a fresh-enough catalog, then fill existing
+      // models. Never blocks plugin startup.
+      void this.reconcile()
+    })
+
+    // Watch the target namespace: any committed provider-model change may
+    // leave fields missing -> reconcile.
+    this.ctx.on('settings/updated', (ns) => {
+      if (ns !== TARGET) return
+      void this.reconcile()
+    })
+  }
+
+  stop(): void {
+    this.scope = undefined
+    this.settings = undefined
+  }
+
+  // ── reads for the settings page ────────────────────────────────────────────
+
+  config(): ModelParametersConfig {
+    if (this.scope !== undefined) {
+      try {
+        return this.scope.get()
+      } catch {
+        // fall through to defaults
+      }
+    }
+    return { ...DEFAULT_CONFIG, providerMap: {}, officialProviders: [...DEFAULT_CONFIG.officialProviders] }
+  }
+
+  catalogSnapshot(): CatalogSnapshot {
+    return this.catalog.snapshotOf()
+  }
+
+  report(): FillReport | null {
+    return this.lastReport
+  }
+
+  /** Force a catalog refresh, then reconcile and report. */
+  async refreshAndReconcile(): Promise<void> {
+    await this.catalog.refresh(this.config().ttlDays)
+    await this.reconcile()
+  }
+
+  /** Update plugin config toggles from the settings page. */
+  async updateConfig(patch: Partial<ModelParametersConfig>): Promise<void> {
+    if (this.scope === undefined) {
+      throw new Error('model-parameters: settings service is not available in this profile')
+    }
+    const current = this.config()
+    await this.scope.update({ ...current, ...patch })
+  }
+
+  // ── reconcile ──────────────────────────────────────────────────────────────
+
+  /**
+   * Fill missing fields on every provider model from the catalog. Serialized:
+   * concurrent triggers (event + backfill) coalesce into one run. Fill-only
+   * guarantees termination: after a write the fields are present, so the next
+   * event produces no ops.
+   */
+  async reconcile(): Promise<void> {
+    if (this.reconciling !== null) return this.reconciling
+    this.reconciling = this.runReconcile().finally(() => {
+      this.reconciling = null
+    })
+    return this.reconciling
+  }
+
+  private async runReconcile(): Promise<void> {
+    const config = this.config()
+    if (!config.enabled) return
+    const settings = this.settings
+    if (settings === undefined) return
+    try {
+      await this.catalog.ensureFresh(config)
+    } catch (error) {
+      this.ctx.logger.warn(`model-parameters: reconcile skipped, catalog unavailable: ${error instanceof Error ? error.message : String(error)}`)
+      return
+    }
+    // Operate on the RAW user section (descriptor.user), not the resolved
+    // value: the resolved section is schema-normalized (pi-ai's loose object
+    // resolution adds empty `input`/`compat` defaults), and persisting that
+    // shape would leak schema-default noise into settings.yaml. The raw
+    // section is exactly what the user document stores.
+    const descriptor = settings.describe({ redactSecrets: false }).find((candidate) => candidate.ns === TARGET)
+    const section = descriptor?.user as { providers?: Record<string, { models?: PiAiModelProfile[] }> } | undefined
+    if (section === undefined || typeof section !== 'object' || section.providers === undefined) return
+
+    const ops: SettingsPathOp[] = []
+    const report: FillReport = { at: Date.now(), filled: 0, touched: 0, unmatched: [] }
+
+    for (const [providerId, profile] of Object.entries(section.providers)) {
+      if (typeof profile !== 'object' || profile === null) continue
+      const models = profile.models
+      if (!Array.isArray(models) || models.length === 0) continue
+      const nextModels: PiAiModelProfile[] = []
+      let changed = false
+      for (const model of models) {
+        const next = this.fillModel(model, providerId, config, report)
+        if (next !== model) changed = true
+        nextModels.push(next)
+      }
+      if (changed) {
+        ops.push({ op: 'set', path: ['providers', providerId, 'models'], value: nextModels })
+        report.touched++
+      }
+    }
+
+    if (ops.length > 0) {
+      try {
+        await settings.mutate(TARGET, ops)
+      } catch (error) {
+        this.ctx.logger.warn(`model-parameters: reconcile persist failed: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+    this.lastReport = report
+    if (report.filled > 0 || report.unmatched.length > 0) {
+      this.ctx.logger.info(
+        `model-parameters: reconcile filled ${report.filled} fields across ${report.touched} providers; ${report.unmatched.length} unmatched (${report.unmatched.slice(0, 5).join(', ')}${report.unmatched.length > 5 ? ', …' : ''})`,
+      )
+    }
+  }
+
+  /** Fill one model entry (fill-only), returning the same object when untouched. */
+  private fillModel(
+    model: PiAiModelProfile,
+    providerId: string,
+    config: ModelParametersConfig,
+    report: FillReport,
+  ): PiAiModelProfile {
+    const entry = this.catalog.resolve(model.id, providerId, config)
+    if (entry === undefined) {
+      report.unmatched.push(`${providerId}/${model.id}`)
+      return model
+    }
+    const next = { ...model }
+    let filledFields = 0
+
+    if (config.fillName && next.name === undefined) {
+      const name = catalogName(entry)
+      if (name !== undefined) {
+        next.name = name
+        filledFields++
+      }
+    }
+    if (config.fillContext && next.contextWindow === undefined && entry.context !== undefined && entry.context > 0) {
+      next.contextWindow = entry.context
+      filledFields++
+    }
+    if (config.fillMaxTokens && next.maxTokens === undefined && entry.output !== undefined && entry.output > 0) {
+      next.maxTokens = entry.output
+      filledFields++
+    }
+    if (config.fillReasoning && next.reasoningEfforts === undefined) {
+      const efforts = identityReasoningEfforts(entry)
+      if (efforts !== undefined) {
+        next.reasoningEfforts = efforts
+        filledFields++
+      }
+    }
+    if (config.fillInput && next.input === undefined) {
+      const input = acceptedInputModalities(entry)
+      if (input !== undefined) {
+        next.input = input
+        filledFields++
+      }
+    }
+    if (filledFields === 0) return model
+    report.filled += filledFields
+    return next
+  }
+}
+
+function catalogName(entry: CatalogEntry): string | undefined {
+  return entry.name !== undefined && entry.name.length > 0 ? entry.name : undefined
+}

package/src/shared/config.ts

@@ -0,0 +1,106 @@
+/**
+ * Plugin configuration and shared constants for @fonlan/dsh-model-parameters.
+ *
+ * The plugin owns the `model-parameters` settings namespace (stored in
+ * settings.yaml) and OBSERVES the `llm-pi-ai` namespace: whenever provider
+ * models are written there with missing capability fields (which is the norm
+ * for a freshly synced gateway), it patches the missing fields from the cached
+ * models.dev catalog.
+ */
+import z from '@deepseek-ai/schemastery'
+
+/** This plugin's own settings namespace. */
+export const PLUGIN_NS = 'model-parameters'
+
+/** The namespace whose models this plugin completes: pi-ai provider profiles. */
+export const TARGET_NS = 'llm-pi-ai'
+
+/** models.dev catalog endpoint. */
+export const CATALOG_URL = 'https://models.dev/api.json'
+
+/** Default provider ids treated as first-party vendors (tie-break for id collisions). */
+export const DEFAULT_OFFICIAL_PROVIDERS: readonly string[] = [
+  'deepseek',
+  'openai',
+  'anthropic',
+  'google',
+  'xai',
+  'moonshotai',
+  'zai',
+  'zhipuai',
+  'minimax',
+  'stepfun',
+  'xiaomi',
+  'meta',
+  'cohere',
+  'nvidia',
+  'alibaba',
+]
+
+/**
+ * dsh pi-ai only accepts these request modalities; models.dev may also list
+ * pdf/audio/video, which must be filtered out before writing (schema rejects
+ * unknown modality values).
+ */
+export const ACCEPTED_INPUT_MODALITIES: readonly string[] = ['text', 'image']
+
+/**
+ * Valid `reasoningEfforts` keys in pi-ai, in escalation order. models.dev
+ * effort values like `default`/`none`/empty are filtered out; only values in
+ * this set are written.
+ */
+export const REASONING_LEVELS: readonly string[] = [
+  'off',
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+]
+
+/** Plugin configuration shape. */
+export interface ModelParametersConfig {
+  /** Master switch: when off, no fills happen (listener is inert). */
+  enabled: boolean
+  /** How many days a cached models.dev catalog is considered fresh. */
+  ttlDays: number
+  /** Fill display name from the catalog when the entry lacks one. */
+  fillName: boolean
+  /** Fill contextWindow when the entry lacks one. */
+  fillContext: boolean
+  /** Fill maxTokens when the entry lacks one. */
+  fillMaxTokens: boolean
+  /** Fill reasoningEfforts (identity dict over offered effort levels) when absent. */
+  fillReasoning: boolean
+  /** Fill input modalities (filtered to text/image) when absent. */
+  fillInput: boolean
+  /** dsh provider id -> models.dev provider id overrides for matching. */
+  providerMap: Record<string, string>
+  /** models.dev provider ids treated as first-party vendors for tie-breaking. */
+  officialProviders: string[]
+}
+
+export const Config: z<ModelParametersConfig> = z.object({
+  enabled: z.boolean().default(true),
+  ttlDays: z.number().min(1).max(90).default(7),
+  fillName: z.boolean().default(true),
+  fillContext: z.boolean().default(true),
+  fillMaxTokens: z.boolean().default(true),
+  fillReasoning: z.boolean().default(true),
+  fillInput: z.boolean().default(true),
+  providerMap: z.dict(z.string()).default({}),
+  officialProviders: z.array(z.string()).default([...DEFAULT_OFFICIAL_PROVIDERS]),
+})
+
+export const DEFAULT_CONFIG: ModelParametersConfig = {
+  enabled: true,
+  ttlDays: 7,
+  fillName: true,
+  fillContext: true,
+  fillMaxTokens: true,
+  fillReasoning: true,
+  fillInput: true,
+  providerMap: {},
+  officialProviders: [...DEFAULT_OFFICIAL_PROVIDERS],
+}