dsh-model-capability-sync 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,197 @@
1
+ /**
2
+ * Settings shapes and provider-entry helpers shared by the plugin's two
3
+ * settings sections: capability sync and name redirect.
4
+ *
5
+ * The browser half only sees `settings.describe` / `settings.mutate`, and that
6
+ * document is structurally open — these helpers keep every unknown field alive
7
+ * instead of narrowing the entry to the fields this plugin understands.
8
+ * @module dsh-model-capability-sync/client/shared
9
+ */
10
+ import type { CapabilityFields } from '../types.ts'
11
+ import type { SortMode } from '../sort.ts'
12
+ import { sortByModelId } from '../sort.ts'
13
+
14
+ /** One settings descriptor as the remote reports it (only the fields used here). */
15
+ export interface SettingsDescriptor {
16
+ ns: string
17
+ revision: number
18
+ value: Record<string, unknown>
19
+ }
20
+
21
+ /** One ordered form edit understood by `settings.mutate`. */
22
+ export interface SettingsPathOp {
23
+ op: 'set' | 'unset'
24
+ path: string[]
25
+ value?: unknown
26
+ }
27
+
28
+ /** The settings surface both sections read and write through. */
29
+ export interface SettingsInjected {
30
+ describeSettings(): Promise<SettingsDescriptor[]>
31
+ mutateSettings(ns: string, ops: SettingsPathOp[], expectedRevision?: number): Promise<SettingsDescriptor>
32
+ }
33
+
34
+ /** A model entry as the provider stores it: structurally open, so unknown fields survive. */
35
+ export type ModelDraft = Record<string, unknown>
36
+
37
+ /** The official adapter this plugin fills capabilities into. */
38
+ export const TARGET_DEFAULT = 'llm-pi-ai'
39
+
40
+ /**
41
+ * How a writable settings namespace reads to a person.
42
+ *
43
+ * A namespace id is an internal identity, so the page names the thing it
44
+ * configures instead. Provenance is a table, not a guess: the client cannot
45
+ * see which package owns a namespace (`settings.describe` reports only
46
+ * `ns/revision/value/base/user`), and inferring "official" from an `llm-`
47
+ * prefix would eventually mislabel a third-party plugin. A namespace this
48
+ * table does not know is shown as a plugin, with its id.
49
+ */
50
+ export const TARGET_DIRECTORY: Record<string, { native: boolean; nameKey: string }> = {
51
+ 'llm-pi-ai': { native: true, nameKey: 'nameLlmPiAi' },
52
+ 'llm-deepseek': { native: true, nameKey: 'nameLlmDeepseek' },
53
+ 'llm-deepseek-account': { native: true, nameKey: 'nameLlmDeepseekAccount' },
54
+ 'llm-newapi': { native: false, nameKey: 'nameLlmNewapi' },
55
+ }
56
+
57
+ /** The bound translate function the shell hands to a section. */
58
+ export type Translate = (key: string, params?: Record<string, unknown>) => string
59
+
60
+ /**
61
+ * Render one namespace as provenance plus a name.
62
+ * @param ns - the settings namespace id.
63
+ * @param t - the bound translate function.
64
+ * @returns copy such as `原生配置 · pi-ai`, never a bare namespace id.
65
+ */
66
+ export function targetLabelOf(ns: string, t: Translate): string {
67
+ const known = TARGET_DIRECTORY[ns]
68
+ if (known === undefined) return `${t('sourcePlugin')} · ${ns}`
69
+ return `${known.native ? t('sourceNative') : t('sourcePlugin')} · ${t(known.nameKey)}`
70
+ }
71
+
72
+ /** The provider dict inside one descriptor's live value. */
73
+ export function providersOf(descriptor: SettingsDescriptor | undefined): Record<string, Record<string, unknown>> {
74
+ const providers = descriptor?.value?.providers
75
+ return typeof providers === 'object' && providers !== null
76
+ ? providers as Record<string, Record<string, unknown>>
77
+ : {}
78
+ }
79
+
80
+ /** The models array of one provider profile. */
81
+ export function modelsOf(provider: Record<string, unknown> | undefined): ModelDraft[] {
82
+ const models = provider?.models
83
+ return Array.isArray(models) ? models.filter((entry): entry is ModelDraft => typeof entry === 'object' && entry !== null) : []
84
+ }
85
+
86
+ /** The models of one provider profile, in display order. */
87
+ export function sortedModelsOf(provider: Record<string, unknown> | undefined, mode: SortMode = 'prefix'): ModelDraft[] {
88
+ return sortByModelId(
89
+ modelsOf(provider),
90
+ model => textOf(model, 'id'),
91
+ model => textOf(model, 'name'),
92
+ mode,
93
+ )
94
+ }
95
+
96
+ /** Read a string field, or the empty string. */
97
+ export function textOf(model: ModelDraft, key: string): string {
98
+ const value = model[key]
99
+ return typeof value === 'string' ? value : ''
100
+ }
101
+
102
+ /**
103
+ * Decide whether a stored field counts as "the user has not said anything".
104
+ *
105
+ * The configuration schema fills defaults for absent fields (`input` reads as
106
+ * `[]`), and those defaults are not user intent, so they count as blank.
107
+ * @param value - the stored value.
108
+ * @returns true when filling the field loses no user intent.
109
+ */
110
+ export function isBlank(value: unknown): boolean {
111
+ if (value === undefined || value === null || value === '') return true
112
+ if (Array.isArray(value)) return value.length === 0
113
+ if (typeof value === 'object') return Object.keys(value as Record<string, unknown>).length === 0
114
+ return false
115
+ }
116
+
117
+ /**
118
+ * Replace one provider's model list inside a descriptor, keeping everything
119
+ * else it carries.
120
+ *
121
+ * A write updates the configuration, so the descriptor the page holds must
122
+ * follow: otherwise the next rebuild from that descriptor (a sort-mode switch,
123
+ * a provider switch, a conflict reload) hands back the pre-write models and the
124
+ * names that were just applied disappear. This is the pure half of that update,
125
+ * separated so it can be tested without a running settings service.
126
+ *
127
+ * Only `providers[key].models` moves. Other providers, and other fields of this
128
+ * provider and its models, are carried over untouched.
129
+ * @param descriptor - the descriptor as the page held it.
130
+ * @param providerKey - which provider was written.
131
+ * @param models - the list that was written.
132
+ * @param revision - the revision the service answered with, when it gave one.
133
+ * @returns a new descriptor; the input is not mutated.
134
+ */
135
+ export function withWrittenModels(
136
+ descriptor: SettingsDescriptor,
137
+ providerKey: string,
138
+ models: readonly ModelDraft[],
139
+ revision: number | undefined,
140
+ ): SettingsDescriptor {
141
+ const providers = providersOf(descriptor)
142
+ const provider = providers[providerKey]
143
+ const nextProviders = provider === undefined
144
+ ? providers
145
+ : { ...providers, [providerKey]: { ...provider, models: [...models] } }
146
+ return {
147
+ ...descriptor,
148
+ ...revision === undefined ? {} : { revision },
149
+ value: { ...descriptor.value, providers: nextProviders },
150
+ }
151
+ }
152
+
153
+ /**
154
+ * Read a hand-typed token count: `128K`, `1M`, `128000`, `1,000,000`.
155
+ *
156
+ * The cells show the short form (`1M`), so the same short form has to be
157
+ * accepted back: a field you can see you can also type. Anything that is not a
158
+ * number with an optional K/M suffix returns undefined, which the caller reads
159
+ * as "no manual value" rather than as zero.
160
+ * @param text - what the cell holds.
161
+ * @returns the count, or undefined when the text is not a count.
162
+ */
163
+ export function parseTokenCount(text: string): number | undefined {
164
+ const trimmed = text.trim().replace(/[,_\s]/g, '')
165
+ if (trimmed === '') return undefined
166
+ const match = /^([0-9]+(?:\.[0-9]+)?)([kKmM])?$/.exec(trimmed)
167
+ if (match === null) return undefined
168
+ const amount = Number(match[1])
169
+ if (!Number.isFinite(amount) || amount <= 0) return undefined
170
+ const suffix = match[2]?.toLowerCase()
171
+ if (suffix === 'k') return Math.round(amount * 1000)
172
+ if (suffix === 'm') return Math.round(amount * 1_000_000)
173
+ return Math.round(amount)
174
+ }
175
+
176
+ /**
177
+ * Overlay hand-typed fields on the ones the catalog gave.
178
+ *
179
+ * The page shows numbers a person can change, because the catalog is not
180
+ * always right and sometimes has nothing at all: a rate-limited proxy route
181
+ * may need a smaller window than the upstream model advertises, and a model
182
+ * the catalog never heard of gets its whole entry typed by hand. Manual values
183
+ * therefore win, and they are applied even when "overwrite" is off — that
184
+ * switch governs catalog values replacing what the user already stored, not
185
+ * values the user just typed.
186
+ * @param base - catalog fields, when there were any.
187
+ * @param manual - fields typed in the table.
188
+ * @returns the fields a write would use.
189
+ */
190
+ export function mergeFields(
191
+ base: CapabilityFields | undefined,
192
+ manual: CapabilityFields | undefined,
193
+ ): CapabilityFields | undefined {
194
+ if (base === undefined) return manual
195
+ if (manual === undefined) return base
196
+ return { ...base, ...manual }
197
+ }
package/src/index.ts ADDED
@@ -0,0 +1,150 @@
1
+ /**
2
+ * Host half: one RPC channel that answers "what does the catalog say about
3
+ * these model ids?".
4
+ *
5
+ * The plugin registers no LLM provider route on purpose — it only supplies
6
+ * facts. The browser half decides which provider entry to write and performs
7
+ * the write through the official settings service, so this half never touches
8
+ * configuration.
9
+ * @module dsh-model-capability-sync
10
+ */
11
+ import { loadCatalog } from './catalog.ts'
12
+ import type { Catalog } from './catalog.ts'
13
+ import { capabilitiesOf } from './mapping.ts'
14
+ import { matchModel } from './match.ts'
15
+ import type { LiveRequest, LiveResponse, LiveRow, PreviewRequest, PreviewResponse, PreviewRow, RpcEnvelope } from './types.ts'
16
+
17
+ /** Cordis plugin name; the profile entry id matches. */
18
+ export const name = 'model-capability-sync'
19
+
20
+ /** The channel is served over the web server, so both services are required. */
21
+ export const inject = ['connection', 'webServer', 'llm']
22
+
23
+ /** Own RPC channel; the browser half calls this exact path. */
24
+ const CHANNEL = '/model-capability-sync'
25
+
26
+ /** The slice of the host context this plugin uses. */
27
+ interface HostContext {
28
+ get(service: string): unknown
29
+ effect(callback: () => (() => void | Promise<void>) | void, label?: string): void
30
+ logger: { warn(message: string): void; error(message: unknown): void }
31
+ }
32
+
33
+ type Handler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<RpcEnvelope<unknown>>
34
+
35
+ /** The connection service's owner-taking registration (see DESIGN in llm-newapi). */
36
+ interface Registrar {
37
+ register(owner: unknown, channel: string, handler: Handler): () => Promise<void>
38
+ }
39
+
40
+ /** Resolve one id against the catalog into a preview row. */
41
+ function previewOne(catalog: Catalog, id: string, aliases: Readonly<Record<string, string>>, name = ''): PreviewRow {
42
+ const named = name === '' ? {} : { name }
43
+ const match = matchModel(catalog, id, aliases, name)
44
+ if (match === undefined) return { id, ...named, reason: 'not in the models.dev catalog' }
45
+ const entry = catalog.byId.get(match.modelId)?.find(candidate => candidate.provider === match.provider)
46
+ if (entry === undefined) return { id, ...named, match, reason: 'catalog entry vanished between match and read' }
47
+ const fields = capabilitiesOf(entry)
48
+ if (Object.keys(fields).length === 0) return { id, ...named, match, reason: 'catalog entry states no capability facts' }
49
+ return { id, ...named, match, fields }
50
+ }
51
+
52
+ /** Serve one `preview` request. */
53
+ async function preview(request: PreviewRequest, signal: AbortSignal): Promise<PreviewResponse> {
54
+ const ids = Array.isArray(request.ids) ? request.ids.filter(id => typeof id === 'string' && id.length > 0) : []
55
+ const catalog = await loadCatalog({ refresh: request.refresh === true, proxyUrl: request.proxyUrl }, signal)
56
+ const aliases = request.aliases ?? {}
57
+ const names = request.names ?? {}
58
+ return {
59
+ fetchedAt: catalog.fetchedAt,
60
+ catalogModels: catalog.modelCount,
61
+ ...catalog.stale === true ? { stale: true } : {},
62
+ rows: ids.map(id => previewOne(catalog, id, aliases, typeof names[id] === 'string' ? names[id] : '')),
63
+ }
64
+ }
65
+
66
+ /** One RPC envelope, never a thrown value: the transport would turn that into an opaque 500. */
67
+ function failure(message: string): RpcEnvelope<never> {
68
+ return { ok: false, error: { code: 'internal', message, details: {} } }
69
+ }
70
+
71
+ /** The LLM registry face this half reads live model metadata through. */
72
+ interface LlmFace {
73
+ resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<{
74
+ inputModalities?: readonly string[]
75
+ context?: { contextWindow: number }
76
+ defaultMaxTokens?: number
77
+ }>
78
+ }
79
+
80
+ /**
81
+ * Read what the adapter that owns `provider` reports right now.
82
+ *
83
+ * A configuration entry and the route a chat request takes can disagree: two
84
+ * plugins may claim one provider route, and only the first registration serves
85
+ * it. This answer is what a request would see, so a filled-in `input` that
86
+ * never takes effect becomes visible instead of inferred.
87
+ * @param llm - the LLM registry.
88
+ * @param request - route and model ids to resolve.
89
+ * @param signal - cancellation for adapter-owned lookups.
90
+ * @returns one row per requested id, in request order.
91
+ */
92
+ async function live(llm: LlmFace, request: LiveRequest, signal: AbortSignal): Promise<LiveResponse> {
93
+ const provider = typeof request.provider === 'string' ? request.provider : ''
94
+ const ids = Array.isArray(request.ids) ? request.ids.filter(id => typeof id === 'string' && id.length > 0) : []
95
+ const rows: LiveRow[] = []
96
+ for (const id of ids) {
97
+ try {
98
+ const info = await llm.resolveModelInfo(provider, id, signal)
99
+ rows.push({
100
+ id,
101
+ ...info.inputModalities === undefined ? {} : { input: [...info.inputModalities] },
102
+ ...info.context === undefined ? {} : { contextWindow: info.context.contextWindow },
103
+ ...info.defaultMaxTokens === undefined ? {} : { maxTokens: info.defaultMaxTokens },
104
+ })
105
+ } catch (error) {
106
+ rows.push({ id, error: error instanceof Error ? error.message : String(error) })
107
+ }
108
+ }
109
+ return { rows }
110
+ }
111
+
112
+ /**
113
+ * Build the channel handler bound to one LLM registry.
114
+ * @param llm - the LLM registry the `live` endpoint reads through, when present.
115
+ * @returns the endpoint dispatcher.
116
+ */
117
+ function createHandler(llm: LlmFace | undefined): Handler {
118
+ return async (endpoint, payload, signal) => {
119
+ try {
120
+ if (endpoint === 'preview') {
121
+ return { ok: true, value: await preview(payload as PreviewRequest, signal) }
122
+ }
123
+ if (endpoint === 'live') {
124
+ if (llm === undefined) return failure('model-capability-sync: no llm service to resolve the live route')
125
+ return { ok: true, value: await live(llm, payload as LiveRequest, signal) }
126
+ }
127
+ return failure(`model-capability-sync: unknown endpoint ${JSON.stringify(endpoint)}`)
128
+ } catch (error) {
129
+ return failure(error instanceof Error ? error.message : String(error))
130
+ }
131
+ }
132
+ }
133
+
134
+ /**
135
+ * Register the channel. The registration rides the calling fiber, so a plugin
136
+ * reload removes the route with it.
137
+ * @param ctx - host context carrying `connection`, `webServer` and `llm`.
138
+ */
139
+ export function apply(ctx: HostContext): void {
140
+ const connection = ctx.get('connection')
141
+ const llm = ctx.get('llm') as LlmFace | undefined
142
+ if (connection === undefined) {
143
+ ctx.logger.warn('model-capability-sync: no connection service; the capability channel is unavailable')
144
+ return
145
+ }
146
+ if (llm === undefined) ctx.logger.warn('model-capability-sync: no llm service; the live route check is unavailable')
147
+ const registrar = connection as Registrar
148
+ const handler = createHandler(llm)
149
+ ctx.effect(() => registrar.register(ctx, CHANNEL, handler), 'model-capability-sync: RPC channel')
150
+ }
package/src/mapping.ts ADDED
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Turning one catalog entry into the capability fields a provider model entry
3
+ * accepts.
4
+ *
5
+ * Everything here is a pure function of catalog data: no gateway call, no
6
+ * guessing beyond the catalog's own facts. A field the catalog does not state
7
+ * stays absent, so the writer never invents a value.
8
+ * @module dsh-model-capability-sync/mapping
9
+ */
10
+ import type { CatalogEntry } from './catalog.ts'
11
+ import type { CapabilityFields, Modality } from './types.ts'
12
+
13
+ /** Thinking levels the harness recognizes, strongest last. */
14
+ const THINKING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
15
+
16
+ /** A positive integer or nothing. */
17
+ function positive(value: unknown): number | undefined {
18
+ return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.round(value) : undefined
19
+ }
20
+
21
+ /** Map the catalog's media list onto the harness's two modalities. */
22
+ function modalitiesOf(entry: CatalogEntry): Modality[] | undefined {
23
+ const declared = entry.model.modalities?.input
24
+ if (declared === undefined) return undefined
25
+ const accepted: Modality[] = []
26
+ for (const media of declared) {
27
+ if (media === 'image' && !accepted.includes('image')) accepted.push('image')
28
+ }
29
+ // A model that lists only images still reads text in practice; the harness
30
+ // always sends text, so `text` is never dropped.
31
+ return ['text', ...accepted]
32
+ }
33
+
34
+ /**
35
+ * Build the reasoning-effort map from the catalog's `effort` option.
36
+ * @returns the dict, `false` when the catalog says the model cannot reason, or
37
+ * `undefined` when the catalog is silent.
38
+ */
39
+ function reasoningOf(entry: CatalogEntry): Record<string, string> | false | undefined {
40
+ const model = entry.model
41
+ if (model.reasoning === false) return false
42
+ const option = model.reasoning_options?.find(candidate => candidate.type === 'effort')
43
+ const values = option?.values ?? []
44
+ const efforts: Record<string, string> = {}
45
+ for (const value of values) {
46
+ if (typeof value !== 'string') continue
47
+ if (!THINKING_LEVELS.has(value)) continue
48
+ efforts[value] = value
49
+ }
50
+ return Object.keys(efforts).length > 0 ? efforts : undefined
51
+ }
52
+
53
+ /**
54
+ * Read every capability the catalog states for one entry.
55
+ *
56
+ * The catalog's display name is deliberately not returned: this plugin fills
57
+ * facts, it never renames a model entry. Renaming has its own section, and the
58
+ * two must stay separable — a fill that also renamed would make the redirect
59
+ * undoable.
60
+ * @param entry - the matched catalog entry.
61
+ * @returns only the fields the catalog actually declares.
62
+ */
63
+ export function capabilitiesOf(entry: CatalogEntry): CapabilityFields {
64
+ const model = entry.model
65
+ const input = modalitiesOf(entry)
66
+ const reasoningEfforts = reasoningOf(entry)
67
+ return {
68
+ ...positive(model.limit?.context) === undefined ? {} : { contextWindow: positive(model.limit?.context) as number },
69
+ ...positive(model.limit?.output) === undefined ? {} : { maxTokens: positive(model.limit?.output) as number },
70
+ ...input === undefined ? {} : { input },
71
+ ...reasoningEfforts === undefined ? {} : { reasoningEfforts },
72
+ }
73
+ }