@tzyc/dsh-model-visibility 0.0.0-stage → 1.9.1

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-model-visibility: one Host row owns the `model-visibility` settings
+# namespace (the persisted list of hidden models); package.json's dsh.client
+# declares the browser half, which binds to this same row id.
+- insert:
+    - id: model-visibility
+      name: '@tzyc/dsh-model-visibility'
+      config: {}

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Model visibility">
+  <rect width="64" height="64" rx="14" fill="#247bbf"/>
+  <rect x="10" y="15" width="44" height="11" rx="5.5" fill="#ffffff" fill-opacity="0.28"/>
+  <rect x="15" y="19" width="14" height="3" rx="1.5" fill="#ffffff"/>
+  <circle cx="46" cy="20.5" r="4.5" fill="#ffffff"/>
+  <rect x="10" y="38" width="44" height="11" rx="5.5" fill="#ffffff" fill-opacity="0.16"/>
+  <rect x="35" y="42" width="14" height="3" rx="1.5" fill="#ffffff" fill-opacity="0.55"/>
+  <circle cx="18" cy="43.5" r="4.5" fill="#ffffff" fill-opacity="0.55"/>
+</svg>

package/index.js

@@ -0,0 +1,476 @@
+/**
+ * Host half of the model-visibility plugin.
+ *
+ * Two jobs:
+ *
+ * 1. Own the `model-visibility` settings namespace: `hidden` is a volatile
+ *    Config field, so the Host settings document persists the browser's choices
+ *    and `settings.describe` projects them back to the Client. The generated
+ *    configuration page is disabled because the plugin's own settings section
+ *    is the editing surface.
+ * 2. Keep a shadow copy of that list outside the profile patch layer
+ *    (`$DSH_HOME/dsh-model-visibility/hidden.json`), because the patch layer is
+ *    rebuilt from scratch in several ordinary situations — a profile repair,
+ *    a plugin reinstall, or any write whose value equals the inherited default
+ *    (the settings writer then deletes the row). Without a shadow copy the row
+ *    silently disappears and every model becomes visible again after the next
+ *    reload. The schema default is seeded from that file, so a rebuilt patch
+ *    layer restores the last known list instead of an empty one.
+ *
+ * Each entry is an opaque `provider/model` key; the Client never parses it.
+ *
+ * @module index.js
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import z from '@deepseek-ai/schemastery'
+
+import { createModelInfoService } from './lib/model-info.js'
+import { createOverrideStore } from './lib/model-overrides.js'
+import { createProviderProbe, readProviderProfiles } from './lib/provider-probe.js'
+import { stripWrittenFields, writeCapabilities } from './lib/provider-write.js'
+import { installImageInputGate } from './lib/image-input-gate.js'
+
+/** Settings namespace this entry owns; also the loader row id. */
+const ENTRY = 'model-visibility'
+/** Config field carrying the hidden model keys. */
+const FIELD = 'hidden'
+/** Shadow store location below `$DSH_HOME`. */
+const STORE_DIR = 'dsh-model-visibility'
+const STORE_FILE = 'hidden.json'
+/** Authenticated same-origin route prefix used by the settings page. */
+const API = '/api/dsh-model-visibility'
+
+/** Absolute path of the shadow copy. */
+function storeFile() {
+  const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
+  return path.join(home, STORE_DIR, STORE_FILE)
+}
+
+/** Keep only string entries, so a hand-edited file can never break the schema. */
+function asKeyList(value) {
+  if (!Array.isArray(value)) return []
+  return value.filter((key) => typeof key === 'string')
+}
+
+/** Read the shadow copy; a missing or unreadable file simply yields an empty list. */
+function readStored() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(storeFile(), 'utf8'))
+    return asKeyList(Array.isArray(parsed) ? parsed : parsed?.[FIELD])
+  } catch (_error) {
+    return []
+  }
+}
+
+/** Replace the shadow copy atomically; a failure must never break the plugin. */
+function writeStored(list) {
+  const file = storeFile()
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const temp = `${file}.${process.pid}.tmp`
+  fs.writeFileSync(temp, `${JSON.stringify({ [FIELD]: list }, null, 2)}\n`)
+  fs.renameSync(temp, file)
+}
+
+/**
+ * Restored default: a rebuilt settings document keeps the last hidden list
+ * instead of falling back to "everything visible".
+ */
+const RESTORED = readStored()
+
+/** Model keys the composer must stop offering, in the order they were hidden. */
+export const Config = z.object({
+  hidden: z.array(z.string()).default(RESTORED).volatile(),
+  /** Probe relay endpoints for capability metadata (set MODEL_VISIBILITY_PROBE=0 to disable). */
+  probe: z.boolean().default(true),
+  /**
+   * Admit image input on relay models the page displays as multimodal. DSH
+   * builds the adapter model from the provider's `defaultInput` (usually
+   * text) when the route leaves `input` empty, so a relay model that really
+   * accepts images is rejected by both the session check and the serializer.
+   * Volatile so flipping the switch reaches the running Host without a reload.
+   */
+  applyInput: z.boolean().default(true).volatile(),
+})
+
+/**
+ * Disable the generated configuration page and keep the shadow copy current.
+ * @param ctx - plugin context.
+ * @param config - resolved plugin config; `hidden` is a stable volatile reference.
+ */
+export function apply(ctx, config) {
+  ctx.inject(['settings'], (child) => {
+    child.effect(() => child.settings.configure({ auto: false }))
+  })
+
+  const logger = ctx.logger ?? console
+
+  // Manual capability overrides live in their own file: they are structured,
+  // change independently of the hidden list, and the request-side image gate
+  // needs a synchronous read. See `lib/model-overrides.js`.
+  const overrides = createOverrideStore({ logger })
+
+  /** Current hidden keys, read through the stable volatile reference. */
+  const liveList = () => {
+    const value = config?.[FIELD]
+    const current = value !== null && typeof value === 'object' && typeof value.get === 'function'
+      ? value.get()
+      : value
+    return asKeyList(current)
+  }
+
+  /** Read one config field, tolerating both a volatile reference and a value. */
+  const liveConfig = (field, fallback) => {
+    const value = config?.[field]
+    const current = value !== null && typeof value === 'object' && typeof value.get === 'function'
+      ? value.get()
+      : value
+    return current === undefined ? fallback : current
+  }
+
+  let written
+  const persist = () => {
+    const list = liveList()
+    const signature = list.join('\u0000')
+    if (signature === written) return
+    try {
+      writeStored(list)
+      written = signature
+    } catch (error) {
+      if (typeof logger.warn === 'function') {
+        logger.warn('model-visibility: could not write the shadow copy')
+        logger.warn(error)
+      }
+    }
+  }
+
+  ctx.effect(() => {
+    const disposers = []
+    /**
+     * A volatile-only settings write updates the reference in place and emits
+     * `loader/volatile-update`; the settings document event covers the same
+     * change when the loader reports it differently.
+     */
+    const onConfigChanged = (paths) => {
+      if (
+        Array.isArray(paths) &&
+        !paths.some((item) => Array.isArray(item) && (item[0] === FIELD || item[0] === 'applyInput'))
+      ) {
+        return
+      }
+      persist()
+    }
+    if (typeof ctx.on === 'function') {
+      disposers.push(
+        ctx.on('loader/volatile-update', (paths) => {
+          onConfigChanged(paths)
+        }),
+      )
+      disposers.push(
+        ctx.on('settings/document-updated', (ns) => {
+          if (ns === ENTRY) onConfigChanged()
+        }),
+      )
+    }
+    return () => {
+      for (const dispose of disposers) {
+        try {
+          if (typeof dispose === 'function') dispose()
+        } catch (_error) {
+          // A listener may already be gone during teardown.
+        }
+      }
+    }
+  }, 'model-visibility: shadow copy')
+
+  ctx.effect(() => {
+    persist()
+    return () => persist()
+  }, 'model-visibility: shadow baseline')
+
+  // The capability catalog is a read-only projection of the live LLM registry,
+  // enriched with the provider profile (settings) and the relay's own model
+  // listing. It is served over an authenticated same-origin route because the
+  // shipped `session.modelCatalog` projection drops context windows and
+  // modalities, and a custom relay reports `input: []` for almost everything.
+  ctx.inject(['llm', 'connection'], (scope) => {
+    const connection = scope.connection
+    if (scope.llm === undefined) {
+      if (typeof logger.warn === 'function') {
+        logger.warn('model-visibility: llm service unavailable; capability route not registered')
+      }
+      return
+    }
+    if (connection === undefined || typeof connection.fetch?.register !== 'function') {
+      if (typeof logger.warn === 'function') {
+        logger.warn('model-visibility: connection.fetch unavailable; capability route not registered')
+      }
+      return
+    }
+
+    // Optional services: without them the page still renders adapter + catalog
+    // facts, it just cannot probe relay endpoints.
+    const settings = typeof scope.get === 'function' ? scope.get('settings') : undefined
+    const credentials = typeof scope.get === 'function' ? scope.get('credentials') : undefined
+    const probeEnabled = config?.probe !== false && process.env.MODEL_VISIBILITY_PROBE !== '0'
+    const probe =
+      probeEnabled && settings !== undefined
+        ? createProviderProbe({ settings, credentials, logger })
+        : null
+
+    // Even with the relay probe disabled, the request-side gate still needs the
+    // provider declarations. Reading them is local and synchronous; cache the
+    // map per settings generation because the gate asks once per model.
+    let fallbackProfiles = null
+    const profilesForGate = () => {
+      if (fallbackProfiles !== null) return fallbackProfiles
+      if (typeof settings?.describe !== 'function') return new Map()
+      try {
+        fallbackProfiles = readProviderProfiles(settings.describe())
+      } catch (_error) {
+        fallbackProfiles = new Map()
+      }
+      return fallbackProfiles
+    }
+    const clearFallbackProfiles = () => {
+      fallbackProfiles = null
+    }
+
+    const service = createModelInfoService(scope.llm, {
+      enrichment: probe === null ? undefined : ({ fresh }) => probe.read({ fresh }),
+      overrides,
+      // Synchronous evidence for the request-side image gate: provider profiles
+      // from the settings document plus the last completed relay probe.
+      context: () => ({
+        profiles: probe === null ? profilesForGate() : probe.profiles(),
+        discovered: probe?.peek()?.discovered,
+        overrides,
+      }),
+    })
+
+    // Make the relay adapter admit images for models the page displays as
+    // multimodal. The patch is read-only: an explicit provider declaration
+    // still wins, and the settings switch can turn the behaviour off.
+    const imageInput = installImageInputGate(scope.llm, {
+      allow: (provider, model) =>
+        liveConfig('applyInput', true) !== false && service.imageInputAllowed(provider, model),
+      warn: (error) => {
+        if (typeof logger.warn === 'function') {
+          logger.warn('model-visibility: image input gate failed')
+          logger.warn(error)
+        }
+      },
+    })
+    scope.effect(() => () => imageInput.dispose(), 'model-visibility: image input gate')
+
+    /** Answer with JSON; the route is diagnostics-friendly on purpose. */
+    const json = (value, status = 200) =>
+      new Response(JSON.stringify(value), {
+        status,
+        headers: {
+          'Content-Type': 'application/json; charset=utf-8',
+          'Cache-Control': 'no-store',
+        },
+      })
+
+    scope.effect(
+      () =>
+        connection.fetch.register({
+          path: `${API}/models`,
+          methods: ['GET'],
+          requestBody: 'buffered',
+          async fetch(request) {
+            let fresh = false
+            let reload = false
+            try {
+              const params = new URL(request.url).searchParams
+              fresh = params.get('fresh') !== null
+              reload = params.get('reload') !== null
+            } catch (_error) {
+              // A malformed URL simply means "use the cached read".
+            }
+            // A hard reload is the page's "re-fetch capabilities" action: drop
+            // every cache and any sweep already in flight, then read again. A
+            // plain `fresh` read bypasses TTLs but still joins an in-flight
+            // sweep, which can be exactly the stale read the user is trying to
+            // escape.
+            if (reload) {
+              service.invalidate()
+              probe?.invalidate()
+              clearFallbackProfiles()
+              overrides.invalidate()
+              imageInput.refresh()
+            }
+            try {
+              return json({ ok: true, value: await service.read({ fresh: fresh || reload }) })
+            } catch (error) {
+              if (typeof logger.warn === 'function') {
+                logger.warn('model-visibility: capability probe failed')
+                logger.warn(error)
+              }
+              return json(
+                {
+                  ok: false,
+                  error: {
+                    code: 'model-info/failed',
+                    message: error instanceof Error ? error.message : String(error),
+                  },
+                },
+                500,
+              )
+            }
+          },
+        }),
+      'model-visibility: capability route',
+    )
+
+    // Manual capability overrides: the page reads the current entries and
+    // writes one model at a time. Both calls are same-origin authenticated by
+    // the connection layer, like the capability route above.
+    scope.effect(
+      () =>
+        connection.fetch.register({
+          path: `${API}/overrides`,
+          methods: ['GET', 'POST'],
+          requestBody: 'buffered',
+          async fetch(request) {
+            const method = String(request.method || 'GET').toUpperCase()
+            if (method === 'GET') {
+              try {
+                return json({ ok: true, value: { overrides: overrides.list() } })
+              } catch (error) {
+                if (typeof logger.warn === 'function') {
+                  logger.warn('model-visibility: could not read model overrides')
+                  logger.warn(error)
+                }
+                return json(
+                  {
+                    ok: false,
+                    error: {
+                      code: 'overrides/failed',
+                      message: error instanceof Error ? error.message : String(error),
+                    },
+                  },
+                  500,
+                )
+              }
+            }
+            if (method !== 'POST') {
+              return json(
+                { ok: false, error: { code: 'overrides/method', message: 'GET or POST' } },
+                405,
+              )
+            }
+            let body
+            try {
+              body = await request.json()
+            } catch (_error) {
+              return json(
+                {
+                  ok: false,
+                  error: { code: 'overrides/body', message: 'expected a JSON override entry' },
+                },
+                400,
+              )
+            }
+            // What the provider schema can express is mirrored into the
+            // provider's own settings, so the composer and the adapter see the
+            // same facts as this page. A refusal is not an error: the local
+            // override still applies, and the response explains the reason.
+            let provider = { written: false, fields: [], reason: 'skipped' }
+            try {
+              if (body !== null && typeof body === 'object' && body.remove === true) {
+                overrides.remove(
+                  typeof body.provider === 'string' ? body.provider : '',
+                  typeof body.model === 'string' ? body.model : '',
+                )
+              } else {
+                const saved = overrides.upsert(body)
+                if (saved !== undefined && body.applyToProvider !== false) {
+                  provider = await writeCapabilities(settings, saved)
+                  if (provider.written) {
+                    const remaining = stripWrittenFields(saved, provider.fields)
+                    const local = Object.keys(remaining).filter(
+                      (key) => key !== 'provider' && key !== 'model',
+                    )
+                    if (local.length === 0) {
+                      overrides.remove(saved.provider, saved.model)
+                    } else {
+                      overrides.upsert(remaining)
+                    }
+                  }
+                }
+              }
+            } catch (error) {
+              if (typeof logger.warn === 'function') {
+                logger.warn('model-visibility: could not save a model override')
+                logger.warn(error)
+              }
+              return json(
+                {
+                  ok: false,
+                  error: {
+                    code: 'overrides/failed',
+                    message: error instanceof Error ? error.message : String(error),
+                  },
+                },
+                500,
+              )
+            }
+            // The new entry outranks every cached capability fact. A provider
+            // write also changed the settings document: refresh the profile
+            // cache so the page immediately shows the declared values instead
+            // of the stale ones (no network sweep is needed for that).
+            service.invalidate()
+            imageInput.refresh()
+            if (provider.written) {
+              clearFallbackProfiles()
+              probe?.noteSettingsChanged()
+            }
+            return json({ ok: true, value: { overrides: overrides.list(), provider } })
+          },
+        }),
+      'model-visibility: override route',
+    )
+
+    // A route/credential change invalidates both the capability cache and (when
+    // it actually changed routing facts) the relay-probe cache. Ordinary
+    // settings writes — hiding one model — only invalidate the capability
+    // snapshot, so a toggle never fans out into a network sweep.
+    scope.effect(() => {
+      const offs = []
+      const invalidateAll = () => {
+        service.invalidate()
+        probe?.invalidate()
+        clearFallbackProfiles()
+        imageInput.refresh()
+      }
+      const noteSettings = () => {
+        service.invalidate()
+        probe?.noteSettingsChanged()
+        clearFallbackProfiles()
+      }
+      if (typeof scope.on === 'function') {
+        offs.push(scope.on('llm/adapters-updated', invalidateAll))
+        offs.push(scope.on('settings/document-updated', noteSettings))
+        for (const event of ['credentials/record-updated', 'credentials/reference-updated']) {
+          try {
+            offs.push(scope.on(event, invalidateAll))
+          } catch (_error) {
+            // Older hosts do not emit every credential event.
+          }
+        }
+      }
+      return () => {
+        for (const off of offs) {
+          try {
+            if (typeof off === 'function') off()
+          } catch (_error) {
+            // The service may already be gone during teardown.
+          }
+        }
+      }
+    }, 'model-visibility: capability cache')
+  })
+}

package/lib/capability-catalog.js

@@ -0,0 +1,137 @@
+/**
+ * Catalog matching and family heuristics.
+ *
+ * The adapter contract only carries `inputModalities`, and for a custom relay
+ * that field is usually the provider's `defaultInput` (text) rather than a fact
+ * about the model. This module fills that gap from two places, in order:
+ *
+ * 1. the pi-ai / models.dev snapshot in `model-catalog.js` (exact id match
+ *    after normalizing aggregator prefixes and request suffixes),
+ * 2. conservative name rules for model families whose capabilities are common
+ *    knowledge (Claude, GPT-4o+, Gemini, Grok 4+, VL/vision variants).
+ *
+ * Everything returned here is *inferred*: callers must label it as such so the
+ * page never presents a guess as an adapter declaration.
+ *
+ * @module lib/capability-catalog
+ */
+
+import { CATALOG_GENERATED_AT, CATALOG_PI_AI_VERSION, MODEL_CATALOG } from './model-catalog.js'
+
+export { CATALOG_GENERATED_AT, CATALOG_PI_AI_VERSION, MODEL_CATALOG }
+
+/** Kinds the page knows how to label. */
+export const MODEL_KINDS = Object.freeze([
+  'chat',
+  'image',
+  'video',
+  'embedding',
+  'rerank',
+  'audio',
+  'classifier',
+  'translation',
+])
+
+const IMAGE_WORDS = /(^|[-_./\s])(image|imagen|images|dall-?e|flux|sdxl|stable-?diffusion|midjourney|mj|seedream|ideogram|recraft|nano-?banana|photon|drawing|text2image|txt2img)([-_./\s]|$)/
+const VIDEO_WORDS = /(^|[-_./\s])(video|sora|veo|kling|hailuo|seedance|pika|runway|vidu|jimeng|wan2|wanx|ltx|mochi|movie|text2video|txt2video)([-_./\s]|$)/
+const EMBED_WORDS = /(^|[-_./\s])(embed|embedding|embeddings|bge|gte|e5|voyage|jina|nv-embed|text-embedding)([-_./\s]|$)/
+const RERANK_WORDS = /(^|[-_./\s])(rerank|reranker|reranking)([-_./\s]|$)/
+const AUDIO_WORDS = /(^|[-_./\s])(tts|speech|asr|whisper|transcribe|transcription|audio|voice|speech-to-text|text-to-speech)([-_./\s]|$)/
+const CLASSIFIER_WORDS = /(^|[-_./\s])(guard|safety|moderation|classifier|censor|content-safety|prompt-guard)([-_./\s]|$)/
+const TRANSLATION_WORDS = /(^|[-_./\s])(translate|translation|translator)([-_./\s]|$)/
+
+const VISION_WORDS = /(^|[-_./\s])(vl|vision|visual|omni|multimodal|mm)([-_./\s]|$)|llava|pixtral|internvl|molmo|idefics|qwen[\d.]*-?vl|glm-[\d.]+v|kimi-.*-vl/
+
+/** Strip aggregator namespaces, request suffixes and resolution variants. */
+export function normalizeModelId(value) {
+  let id = String(value ?? '').trim().toLowerCase()
+  if (id === '') return ''
+  id = id.replace(/^~/, '')
+  // Providers may stack request variants (for example `:free:thinking`).
+  // Strip them one at a time so aliases remain stable without broad folding.
+  let previous
+  do {
+    previous = id
+    id = id.replace(/:(batch|free|extended|thinking|online|nitro)$/, '')
+    id = id.replace(/-(free|batch)$/, '')
+  } while (id !== previous)
+  const slash = id.lastIndexOf('/')
+  if (slash !== -1) id = id.slice(slash + 1)
+  id = id.replace(/^(global|us|eu|apac|jp|au|ca)\./, '')
+  id = id.replace(/^(anthropic|openai|google|xai|x-ai|meta|mistralai|moonshotai|minimax|nvidia|qwen|z-ai|zai|deepseek|bytedance-seed)\./, '')
+  return id
+}
+
+/** Lookup keys for one model id, most specific first. */
+export function modelIdVariants(value) {
+  const base = normalizeModelId(value)
+  if (base === '') return []
+  const variants = [base]
+  const withoutResolution = base.replace(/-(4k|2k|8k|hd|uhd)$/, '')
+  if (withoutResolution !== base) variants.push(withoutResolution)
+  const withoutSuffix = withoutResolution.replace(/-(latest|preview|new)$/, '')
+  if (!variants.includes(withoutSuffix)) variants.push(withoutSuffix)
+  const compact = base.replace(/[^a-z0-9]+/g, '')
+  if (compact !== '' && !variants.includes(compact)) variants.push(compact)
+  return variants
+}
+
+/** Exact/alias index over the generated snapshot. */
+const INDEX = (() => {
+  const index = new Map()
+  for (const [id, entry] of Object.entries(MODEL_CATALOG)) {
+    for (const variant of modelIdVariants(id)) {
+      if (!index.has(variant)) index.set(variant, { id, ...entry })
+    }
+  }
+  return index
+})()
+
+/**
+ * Find the snapshot entry for one model id.
+ * @param value - model id as any provider spells it.
+ * @returns `{ id, type, input?, output?, reasoning?, contextWindow?, maxTokens?, provider? }` or undefined.
+ */
+export function lookupCatalogModel(value) {
+  for (const variant of modelIdVariants(value)) {
+    const found = INDEX.get(variant)
+    if (found !== undefined) return found
+  }
+  return undefined
+}
+
+/** Coarse kind from the id/name alone. */
+export function inferModelKind(id, name = '') {
+  const text = `${String(id ?? '')} ${String(name ?? '')}`.toLowerCase()
+  if (text.trim() === '') return undefined
+  if (VIDEO_WORDS.test(text)) return 'video'
+  if (IMAGE_WORDS.test(text)) return 'image'
+  if (RERANK_WORDS.test(text)) return 'rerank'
+  if (EMBED_WORDS.test(text)) return 'embedding'
+  if (AUDIO_WORDS.test(text)) return 'audio'
+  if (CLASSIFIER_WORDS.test(text)) return 'classifier'
+  if (TRANSLATION_WORDS.test(text)) return 'translation'
+  return 'chat'
+}
+
+/** Modalities inferred from a chat model family; never claims text-only. */
+export function inferInputModalities(id, name = '') {
+  const text = `${String(id ?? '')} ${String(name ?? '')}`.toLowerCase()
+  if (VISION_WORDS.test(text)) return ['text', 'image']
+  if (/claude|fable|opus|sonnet|haiku/.test(text)) return ['text', 'image']
+  if (/gpt-4o|gpt-4\.1|gpt-5|gpt-6|chatgpt/.test(text)) return ['text', 'image']
+  if (/gemini/.test(text)) return ['text', 'image']
+  if (/grok-[3-9]/.test(text)) return ['text', 'image']
+  if (/llama-4|llama-3\.2-vision/.test(text)) return ['text', 'image']
+  return undefined
+}
+
+/** Kinds that produce assets instead of conversation turns. */
+export function isGenerationKind(kind) {
+  return kind === 'image' || kind === 'video' || kind === 'audio'
+}
+
+/** True when the kind should hide reasoning/context/text tags. */
+export function isNonChatKind(kind) {
+  return kind !== undefined && kind !== 'chat'
+}