switchback-core 2026.11.1 → 2026.11.2

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "switchback-core",
3
- "version": "2026.11.1",
3
+ "version": "2026.11.2",
4
4
  "type": "module",
5
5
  "description": "Host-agnostic core for switchback: fallback routing, error classification ports, block state and configuration.",
6
6
  "license": "MIT",
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Which decision models carry their own connection details, and which depend on
3
+ * a host's classifier catalog.
4
+ *
5
+ * This is the one question the config loader deliberately does *not* answer: an
6
+ * address without a `baseUrl` is perfectly valid on a host that has a catalog
7
+ * (pi resolves `typesafe/jev-latest` straight from its model registry), and it
8
+ * is unusable on a host that does not (OpenCode has no catalog, so the address
9
+ * needs `decisionProviders.<provider>` or a `decisionModels.<address>` entry).
10
+ *
11
+ * Both answers are computed here from the resolved config, so the pi check and
12
+ * the OpenCode notice agree on what "has a connection" means and no host repeats
13
+ * the precedence rule (address override wins over the provider entry).
14
+ */
15
+
16
+ import type { ResolvedSwitchbackFileConfig } from "./types.ts";
17
+
18
+ /**
19
+ * The minimum shape a connection lookup needs. Both the file config and the
20
+ * resolved config satisfy it, so the dialogue (which re-reads the file) and the
21
+ * host checks (which pass the resolved config) share one rule.
22
+ */
23
+ interface ConnectionSource {
24
+ readonly decisionModels?: Readonly<Record<string, { readonly baseUrl?: string }>>;
25
+ readonly decisionProviders?: Readonly<Record<string, { readonly baseUrl?: string }>>;
26
+ }
27
+
28
+ /** Split a `provider/id` decision-model address; undefined parts mean a malformed one. */
29
+ export function splitDecisionModelAddress(address: string): { provider: string; id: string } | undefined {
30
+ const slash = address.indexOf("/");
31
+ if (slash <= 0 || slash === address.length - 1) return undefined;
32
+ return { provider: address.slice(0, slash), id: address.slice(slash + 1) };
33
+ }
34
+
35
+ /** The connection details an address resolves to: its own entry first, then its provider's. */
36
+ export function decisionModelConnection(config: ConnectionSource, address: string): { baseUrl?: string } | undefined {
37
+ const parts = splitDecisionModelAddress(address);
38
+ return config.decisionModels?.[address] ?? (parts === undefined ? undefined : config.decisionProviders?.[parts.provider]);
39
+ }
40
+
41
+ /** Every decision-model address the config references, de-duplicated, in model order. */
42
+ export function referencedDecisionModelAddresses(config: ResolvedSwitchbackFileConfig): string[] {
43
+ const addresses = new Set<string>();
44
+ for (const model of config.models) {
45
+ if (model.decisionModel !== undefined) addresses.add(`${model.decisionModel.provider}/${model.decisionModel.id}`);
46
+ }
47
+ return [...addresses];
48
+ }
49
+
50
+ /**
51
+ * Referenced addresses that carry no `baseUrl` and therefore need a classifier
52
+ * catalog. On pi these resolve from the registry; on OpenCode they are the exact
53
+ * set that silently cannot classify, which is the only case worth a notice.
54
+ */
55
+ export function decisionModelsWithoutConnection(config: ResolvedSwitchbackFileConfig): string[] {
56
+ return referencedDecisionModelAddresses(config).filter(
57
+ (address) => decisionModelConnection(config, address)?.baseUrl === undefined,
58
+ );
59
+ }
@@ -224,9 +224,9 @@ export function moveFallback(loaded: LoadedConfig, virtualId: string, from: numb
224
224
  /**
225
225
  * Set or clear a model's decision model. `null` clears the key (the model then
226
226
  * reports and blind-cycles without classifying). The value is a decision-model
227
- * address ("provider/model-id"); connection details, when the address needs a
228
- * direct endpoint, live in the top-level `decisionModels:` map under the same
229
- * address.
227
+ * address ("provider/model-id"); the connection details it inherits live in
228
+ * `decisionProviders:` under the provider, or in a `decisionModels:` entry at
229
+ * the same address when that one model needs its own endpoint.
230
230
  */
231
231
  export function setDecisionModel(loaded: LoadedConfig, virtualId: string, address: string | null): void {
232
232
  const { node } = findModelNode(loaded, virtualId);
@@ -366,6 +366,114 @@ export function countDecisionModelReferences(loaded: LoadedConfig, address: stri
366
366
  return count;
367
367
  }
368
368
 
369
+ /** A `decisionProviders:` map value as the editor accepts it. */
370
+ export interface DecisionProviderInput {
371
+ /** Provider id - the map key, and the first half of a decision-model address. */
372
+ provider: string;
373
+ /** Direct SystemOne endpoint; omit for catalog resolution. */
374
+ baseUrl?: string;
375
+ /**
376
+ * Secret-store name, written as `secret:<name>`. Omit for an endpoint that
377
+ * ignores the bearer token; the entry then carries `apiKey: local`.
378
+ */
379
+ apiKeySecretName?: string;
380
+ }
381
+
382
+ /** Field-level patch for an existing provider; `null` clears the field. */
383
+ export type DecisionProviderPatch = DecisionModelPatch;
384
+
385
+ function requireDecisionProvidersMap(loaded: LoadedConfig): YAMLMap {
386
+ const map = loaded.doc.get("decisionProviders");
387
+ if (map === undefined || map === null) {
388
+ const created = loaded.doc.createNode({}) as YAMLMap;
389
+ loaded.doc.set("decisionProviders", created);
390
+ return created;
391
+ }
392
+ if (!isMap(map)) throw new ConfigError("decisionProviders must be a map keyed by provider id", loaded.path);
393
+ return map;
394
+ }
395
+
396
+ /** Find a decisionProviders entry node by provider id (the map key). */
397
+ function findDecisionProviderNode(loaded: LoadedConfig, provider: string): { map: YAMLMap; node: YAMLMap } {
398
+ const map = requireDecisionProvidersMap(loaded);
399
+ const node = map.get(provider, true);
400
+ if (node === undefined || node === null || !isMap(node)) {
401
+ throw new ConfigError(`decisionProviders.${provider} not found`, loaded.path);
402
+ }
403
+ return { map, node };
404
+ }
405
+
406
+ /**
407
+ * Add a provider's connection details. One entry serves every decision model of
408
+ * that provider, so this is what a new decision model normally needs - not a
409
+ * `decisionModels` entry per model.
410
+ */
411
+ export function addDecisionProvider(loaded: LoadedConfig, input: DecisionProviderInput): void {
412
+ const map = requireDecisionProvidersMap(loaded);
413
+ if (map.has(input.provider)) {
414
+ throw new ConfigError(`decisionProviders already contains "${input.provider}"`, loaded.path);
415
+ }
416
+ map.set(
417
+ input.provider,
418
+ decisionModelToNode(loaded.doc, {
419
+ address: input.provider,
420
+ ...(input.baseUrl !== undefined ? { baseUrl: input.baseUrl } : {}),
421
+ ...(input.apiKeySecretName !== undefined ? { apiKeySecretName: input.apiKeySecretName } : {}),
422
+ }),
423
+ );
424
+ }
425
+
426
+ /** Patch one provider's connection details. */
427
+ export function updateDecisionProvider(
428
+ loaded: LoadedConfig,
429
+ provider: string,
430
+ patch: DecisionProviderPatch,
431
+ ): void {
432
+ const { map, node } = findDecisionProviderNode(loaded, provider);
433
+ if (patch.baseUrl !== undefined) {
434
+ if (patch.baseUrl === null) {
435
+ node.delete("baseUrl");
436
+ // apiKey is only valid alongside baseUrl; clearing baseUrl clears it.
437
+ node.delete("apiKey");
438
+ } else {
439
+ node.set("baseUrl", patch.baseUrl);
440
+ if (!node.has("apiKey")) node.set("apiKey", "local");
441
+ }
442
+ }
443
+ if (patch.apiKeySecretName !== undefined) {
444
+ node.set("apiKey", patch.apiKeySecretName === null ? "local" : `secret:${patch.apiKeySecretName}`);
445
+ }
446
+ // An update that clears the whole connection would leave an empty `{}`
447
+ // behind; drop the key instead, like removeDecisionProvider does.
448
+ if (node.get("baseUrl") === undefined && node.get("apiKey") === undefined) {
449
+ map.delete(provider);
450
+ if (map.items.length === 0) loaded.doc.delete("decisionProviders");
451
+ }
452
+ }
453
+
454
+ /**
455
+ * Remove a provider's connection details. Per-address `decisionModels` entries
456
+ * are left alone (they may carry their own endpoint), and chains are not
457
+ * rewritten: their addresses simply fall back to catalog resolution.
458
+ */
459
+ export function removeDecisionProvider(loaded: LoadedConfig, provider: string): void {
460
+ const { map } = findDecisionProviderNode(loaded, provider);
461
+ map.delete(provider);
462
+ // An empty map is litter: drop the key so the file reads as if no entry was ever made.
463
+ if (map.items.length === 0) loaded.doc.delete("decisionProviders");
464
+ }
465
+
466
+ /** How many configured models use a decision model from this provider. */
467
+ export function countDecisionProviderReferences(loaded: LoadedConfig, provider: string): number {
468
+ let count = 0;
469
+ for (const item of requireModelsSeq(loaded).items) {
470
+ if (item === null || !isMap(item)) continue;
471
+ const address = item.get("decisionModel");
472
+ if (typeof address === "string" && address.slice(0, address.indexOf("/")) === provider) count += 1;
473
+ }
474
+ return count;
475
+ }
476
+
369
477
  /**
370
478
  * Set or clear a model's `idleReset:` option. A duration ("30m", "2h", ...)
371
479
  * returns to the head of the fallback list after that much idle time;
package/src/config.ts CHANGED
@@ -40,6 +40,8 @@ import type {
40
40
  DecisionModelConfig,
41
41
  DecisionModelEntry,
42
42
  DecisionModelId,
43
+ DecisionProviderConfig,
44
+ DecisionProviderEntry,
43
45
  ModelId,
44
46
  ResolvedSwitchbackConfig,
45
47
  ResolvedSwitchbackFileConfig,
@@ -53,7 +55,7 @@ const VIRTUAL_ID = "auto";
53
55
  const CONFIG_BASENAME = "switchback";
54
56
 
55
57
  /** Recognised keys, per level. Anything else is reported as a warning, not an error. */
56
- const FILE_KEYS = ["models", "decisionModels", "debug"] as const;
58
+ const FILE_KEYS = ["models", "decisionProviders", "decisionModels", "debug"] as const;
57
59
  const MODEL_KEYS = ["id", "name", "fallbacks", "decisionModel", "idleReset"] as const;
58
60
  const DECISION_MODEL_KEYS = ["baseUrl", "apiKey"] as const;
59
61
 
@@ -141,6 +143,23 @@ function isRecord(value: unknown): value is Record<string, unknown> {
141
143
  return typeof value === "object" && value !== null && !Array.isArray(value);
142
144
  }
143
145
 
146
+ /**
147
+ * Validate a provider id: a single YAML map key that names a provider, without
148
+ * the "/" a decision-model address has (the model id is the second half of the
149
+ * address and never part of the provider key).
150
+ */
151
+ function parseProviderId(value: string, where: string): string {
152
+ if (value.length === 0) throw new ConfigError(`${where} must be a non-empty provider id`, where);
153
+ if (value.includes("/")) {
154
+ throw new ConfigError(
155
+ `${where} must be a provider id (e.g. "ollama"), not a "provider/model" address - the model id belongs in models[].decisionModel`,
156
+ where,
157
+ );
158
+ }
159
+ if (/\s/u.test(value)) throw new ConfigError(`${where} must not contain whitespace`, where);
160
+ return value;
161
+ }
162
+
144
163
  function parseModelId(value: unknown, where: string): ModelId {
145
164
  if (typeof value !== "string") throw new ConfigError(`${where} must be a string (e.g. "provider/id")`, where);
146
165
  if (value.indexOf("/") <= 0) throw new ConfigError(`${where} must be of the form "provider/id"`, where);
@@ -190,8 +209,97 @@ function splitAddress(address: DecisionModelId, where: string): { provider: stri
190
209
  }
191
210
 
192
211
  /**
193
- * Parse the `decisionModels:` map. Each key is a decision-model address; the
194
- * value carries the connection details for a direct SystemOne endpoint.
212
+ * Validate one connection-details map value. `baseUrl` and `apiKey` come as a
213
+ * pair: a direct endpoint needs a bearer token even when the endpoint ignores it
214
+ * (`apiKey: local`), and a token without an endpoint would be dead weight.
215
+ *
216
+ * No warning is emitted when both are absent: the address then resolves through
217
+ * the host's classifier catalog, which is a perfectly valid configuration (pi
218
+ * does exactly that). Whether that is a problem is a *host* question - pi has a
219
+ * catalog, OpenCode does not - so it is answered where the host knows, not here.
220
+ */
221
+ function parseConnectionEntry(
222
+ rawEntry: unknown,
223
+ where: string,
224
+ path: string,
225
+ warnings: string[],
226
+ ): DecisionModelEntry {
227
+ if (!isRecord(rawEntry)) throw new ConfigError(`${where} must be an object with baseUrl and apiKey`, path);
228
+ noteUnknownKeys(rawEntry, DECISION_MODEL_KEYS, where, warnings);
229
+
230
+ const rawBaseUrl = rawEntry["baseUrl"];
231
+ let baseUrl: string | undefined;
232
+ if (rawBaseUrl !== undefined) {
233
+ if (typeof rawBaseUrl !== "string" || rawBaseUrl.length === 0) {
234
+ throw new ConfigError(`${where}.baseUrl must be a non-empty URL string`, path);
235
+ }
236
+ let parsed: URL;
237
+ try {
238
+ parsed = new URL(rawBaseUrl);
239
+ } catch {
240
+ throw new ConfigError(`${where}.baseUrl is not a valid URL: ${rawBaseUrl}`, path);
241
+ }
242
+ if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
243
+ throw new ConfigError(`${where}.baseUrl must be http(s), got ${parsed.protocol}`, path);
244
+ }
245
+ baseUrl = rawBaseUrl;
246
+ }
247
+
248
+ const rawApiKey = rawEntry["apiKey"];
249
+ let apiKey: string | undefined;
250
+ if (rawApiKey !== undefined) {
251
+ if (typeof rawApiKey !== "string" || rawApiKey.length === 0) {
252
+ throw new ConfigError(`${where}.apiKey must be a non-empty string`, path);
253
+ }
254
+ apiKey = rawApiKey;
255
+ }
256
+ if (baseUrl !== undefined && apiKey === undefined) {
257
+ throw new ConfigError(
258
+ `${where}.apiKey is required with baseUrl - use "local" for endpoints that ignore the bearer token`,
259
+ path,
260
+ );
261
+ }
262
+ if (apiKey !== undefined && baseUrl === undefined) {
263
+ throw new ConfigError(`${where}.apiKey requires ${where}.baseUrl`, path);
264
+ }
265
+ return {
266
+ ...(baseUrl !== undefined ? { baseUrl } : {}),
267
+ ...(apiKey !== undefined ? { apiKey } : {}),
268
+ };
269
+ }
270
+
271
+ /**
272
+ * Parse the `decisionProviders:` map: connection details keyed by provider id,
273
+ * shared by every decision model of that provider.
274
+ */
275
+ function parseDecisionProviders(
276
+ value: unknown,
277
+ path: string,
278
+ warnings: string[],
279
+ ): Record<string, DecisionProviderEntry> | undefined {
280
+ if (value === undefined) return undefined;
281
+ if (Array.isArray(value)) {
282
+ warnings.push(
283
+ `decisionProviders is a map keyed by provider id (e.g. ollama: { baseUrl, apiKey }); the list form was ignored (${path})`,
284
+ );
285
+ return undefined;
286
+ }
287
+ if (!isRecord(value)) throw new ConfigError("decisionProviders must be an object keyed by provider id", path);
288
+ const entries: Record<string, DecisionProviderEntry> = {};
289
+ for (const [provider, rawEntry] of Object.entries(value)) {
290
+ const where = `decisionProviders.${provider}`;
291
+ parseProviderId(provider, where);
292
+ entries[provider] = parseConnectionEntry(rawEntry, where, path, warnings);
293
+ }
294
+ return entries;
295
+ }
296
+
297
+ /**
298
+ * Parse the `decisionModels:` map: per-address connection overrides. Each key is
299
+ * a decision-model address; the value carries the connection details for a
300
+ * direct SystemOne endpoint. Normally the same details live once in
301
+ * `decisionProviders:` instead; this map exists for the one-model-of-a-provider
302
+ * case and for files written before the provider section existed.
195
303
  */
196
304
  function parseDecisionModels(
197
305
  value: unknown,
@@ -210,64 +318,17 @@ function parseDecisionModels(
210
318
  for (const [address, rawEntry] of Object.entries(value)) {
211
319
  const where = `decisionModels.${address}`;
212
320
  parseModelId(address, where);
213
- if (!isRecord(rawEntry)) throw new ConfigError(`${where} must be an object with baseUrl and apiKey`, path);
214
- noteUnknownKeys(rawEntry, DECISION_MODEL_KEYS, where, warnings);
215
-
216
- const rawBaseUrl = rawEntry["baseUrl"];
217
- let baseUrl: string | undefined;
218
- if (rawBaseUrl !== undefined) {
219
- if (typeof rawBaseUrl !== "string" || rawBaseUrl.length === 0) {
220
- throw new ConfigError(`${where}.baseUrl must be a non-empty URL string`, path);
221
- }
222
- let parsed: URL;
223
- try {
224
- parsed = new URL(rawBaseUrl);
225
- } catch {
226
- throw new ConfigError(`${where}.baseUrl is not a valid URL: ${rawBaseUrl}`, path);
227
- }
228
- if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
229
- throw new ConfigError(`${where}.baseUrl must be http(s), got ${parsed.protocol}`, path);
230
- }
231
- baseUrl = rawBaseUrl;
232
- }
233
-
234
- const rawApiKey = rawEntry["apiKey"];
235
- let apiKey: string | undefined;
236
- if (rawApiKey !== undefined) {
237
- if (typeof rawApiKey !== "string" || rawApiKey.length === 0) {
238
- throw new ConfigError(`${where}.apiKey must be a non-empty string`, path);
239
- }
240
- apiKey = rawApiKey;
241
- }
242
- if (baseUrl !== undefined && apiKey === undefined) {
243
- // A direct endpoint needs a bearer token to send. Local servers ignore
244
- // it, but the token is still the thing that makes "direct endpoint"
245
- // explicit rather than a silent default.
246
- throw new ConfigError(
247
- `${where}.apiKey is required with baseUrl - use "local" for endpoints that ignore the bearer token`,
248
- path,
249
- );
250
- }
251
- if (apiKey !== undefined && baseUrl === undefined) {
252
- throw new ConfigError(`${where}.apiKey requires ${where}.baseUrl`, path);
253
- }
254
- if (baseUrl === undefined) {
255
- warnings.push(
256
- `${where} has no connection details; it can only resolve through a classifier catalog (pi has one, OpenCode does not)`,
257
- );
258
- }
259
- entries[address] = {
260
- ...(baseUrl !== undefined ? { baseUrl } : {}),
261
- ...(apiKey !== undefined ? { apiKey } : {}),
262
- };
321
+ entries[address] = parseConnectionEntry(rawEntry, where, path, warnings);
263
322
  }
264
323
  return entries;
265
324
  }
266
325
 
267
326
  /**
268
- * Resolve a chain's `decisionModel:` address against the `decisionModels:` map.
327
+ * Resolve a chain's `decisionModel:` address against the config's connection
328
+ * details.
269
329
  *
270
- * A map entry with a `baseUrl` pins the endpoint. Without one the address stays
330
+ * Precedence: a `decisionModels:` entry at the exact address wins, otherwise the
331
+ * provider's `decisionProviders:` entry applies. With neither the address stays
271
332
  * catalog-resolved, which pi can do and OpenCode cannot - that stays a visible
272
333
  * "no classifier" cycle there instead of a load error, because the same file is
273
334
  * valid on pi.
@@ -275,10 +336,11 @@ function parseDecisionModels(
275
336
  export function resolveDecisionModel(
276
337
  decisionModels: Record<DecisionModelId, DecisionModelConfig> | undefined,
277
338
  address: DecisionModelId | undefined,
339
+ decisionProviders?: Record<string, DecisionProviderConfig>,
278
340
  ): DecisionModelConfig | undefined {
279
341
  if (address === undefined) return undefined;
280
342
  const { provider, id } = splitAddress(address, "decisionModel");
281
- const entry = decisionModels?.[address];
343
+ const entry = decisionModels?.[address] ?? decisionProviders?.[provider];
282
344
  return {
283
345
  provider,
284
346
  id,
@@ -292,6 +354,8 @@ export type {
292
354
  SwitchbackFileConfig,
293
355
  DecisionModelConfig,
294
356
  DecisionModelEntry,
357
+ DecisionProviderEntry,
358
+ DecisionProviderConfig,
295
359
  DecisionModelId,
296
360
  } from "./types.ts";
297
361
 
@@ -365,11 +429,28 @@ export function resolveSecretApiKey(
365
429
  return value;
366
430
  }
367
431
 
368
- /** Resolve every chain's `decisionModel:` address against the map, and the map's secret refs. */
432
+ /**
433
+ * Resolve the config into what the router consumes: provider/address connection
434
+ * details with their secret refs resolved, and every chain's address merged with
435
+ * the connection details it inherits (address override first, then provider).
436
+ */
369
437
  function resolveFile(
370
438
  file: SwitchbackFileConfig,
371
439
  secrets: { get(name: string): string | undefined } | undefined = undefined,
372
440
  ): ResolvedSwitchbackFileConfig {
441
+ const resolvedDecisionProviders: Record<string, DecisionProviderConfig> | undefined =
442
+ file.decisionProviders === undefined
443
+ ? undefined
444
+ : Object.fromEntries(
445
+ Object.entries(file.decisionProviders).map(([provider, entry]) => {
446
+ const apiKey = resolveSecretApiKey(entry.apiKey, secrets);
447
+ const descriptor: DecisionProviderConfig = {
448
+ ...(entry.baseUrl !== undefined ? { baseUrl: entry.baseUrl } : {}),
449
+ ...(apiKey !== undefined ? { apiKey } : {}),
450
+ };
451
+ return [provider, descriptor];
452
+ }),
453
+ );
373
454
  const resolvedDecisionModels: Record<DecisionModelId, DecisionModelConfig> | undefined =
374
455
  file.decisionModels === undefined
375
456
  ? undefined
@@ -389,9 +470,12 @@ function resolveFile(
389
470
  return {
390
471
  models: file.models.map((model) => {
391
472
  const { decisionModel, ...rest } = model;
392
- const resolved = resolveDecisionModel(resolvedDecisionModels, decisionModel);
473
+ const resolved = resolveDecisionModel(resolvedDecisionModels, decisionModel, resolvedDecisionProviders);
393
474
  return resolved === undefined ? rest : { ...rest, decisionModel: resolved };
394
475
  }),
476
+ ...(resolvedDecisionProviders !== undefined && Object.keys(resolvedDecisionProviders).length > 0
477
+ ? { decisionProviders: resolvedDecisionProviders }
478
+ : {}),
395
479
  ...(resolvedDecisionModels !== undefined && Object.keys(resolvedDecisionModels).length > 0
396
480
  ? { decisionModels: resolvedDecisionModels }
397
481
  : {}),
@@ -432,21 +516,15 @@ function parseFileConfig(value: unknown, path: string, warnings: string[]): Swit
432
516
  if (rawDebug !== undefined && typeof rawDebug !== "boolean") {
433
517
  throw new ConfigError("debug must be a boolean", path);
434
518
  }
519
+ const decisionProviders = parseDecisionProviders(value["decisionProviders"], path, warnings);
435
520
  const decisionModels = parseDecisionModels(value["decisionModels"], path, warnings);
436
- // A `decisionModels` entry no chain references is harmless but almost always a
437
- // leftover: warn (do not fail) so the block does not quietly rot.
438
- if (decisionModels !== undefined) {
439
- const referenced = new Set(parsed.map((model) => model.decisionModel).filter((id) => id !== undefined));
440
- for (const address of Object.keys(decisionModels)) {
441
- if (!referenced.has(address)) {
442
- warnings.push(
443
- `decisionModels.${address} is not referenced by any models[].decisionModel and was ignored`,
444
- );
445
- }
446
- }
447
- }
521
+ // Unreferenced connection details are not a problem: a provider entry is shared
522
+ // by every model of that provider (and may be prepared before a chain names
523
+ // one), so nothing is "ignored" and nothing can rot. The earlier warning here
524
+ // read like a failure report for a perfectly valid config.
448
525
  return {
449
526
  models: parsed,
527
+ ...(decisionProviders !== undefined ? { decisionProviders } : {}),
450
528
  ...(decisionModels !== undefined ? { decisionModels } : {}),
451
529
  ...(rawDebug !== undefined ? { debug: rawDebug } : {}),
452
530
  };
@@ -499,8 +577,11 @@ export interface SecretResolver {
499
577
  * `createSecretStore()`; tests pass a fake or leave it undefined.
500
578
  *
501
579
  * `warnings` carries recognised-but-suspicious findings (unknown keys, retired
502
- * keys, unreferenced decision models). They never fail the load: a host shows
503
- * them through its own notify channel.
580
+ * keys, malformed optional values). They never fail the load: a host shows them
581
+ * through its own notify channel. Host *capability* findings are deliberately
582
+ * not here - a decision model that relies on a classifier catalog is fine on pi
583
+ * and impossible on OpenCode, so that judgement belongs to the host
584
+ * (`packages/opencode/src/decision-model-check.ts`).
504
585
  */
505
586
  export function loadConfig(secrets?: SecretResolver): {
506
587
  config: ResolvedSwitchbackFileConfig;
package/src/index.ts CHANGED
@@ -97,19 +97,24 @@ export {
97
97
  export type { SwitchbackConfig, SwitchbackFileConfig, DecisionModelConfig, SecretResolver } from "./config.ts";
98
98
  export type {
99
99
  DecisionModelEntry,
100
+ DecisionProviderConfig,
101
+ DecisionProviderEntry,
100
102
  DecisionModelId,
101
103
  ResolvedSwitchbackConfig,
102
104
  ResolvedSwitchbackFileConfig,
103
105
  } from "./types.ts";
104
106
  export {
105
107
  addDecisionModel,
108
+ addDecisionProvider,
106
109
  addFallback,
107
110
  addVirtualModel,
108
111
  countDecisionModelReferences,
112
+ countDecisionProviderReferences,
109
113
  loadConfigFile,
110
114
  moveFallback,
111
115
  readConfigFile,
112
116
  removeDecisionModel,
117
+ removeDecisionProvider,
113
118
  removeFallback,
114
119
  removeVirtualModel,
115
120
  renameDecisionModel,
@@ -121,14 +126,27 @@ export {
121
126
  setIdleReset,
122
127
  setVirtualModelName,
123
128
  updateDecisionModel,
129
+ updateDecisionProvider,
130
+ } from "./config-editor.ts";
131
+ export type {
132
+ DecisionModelInput,
133
+ DecisionModelPatch,
134
+ DecisionProviderInput,
135
+ DecisionProviderPatch,
136
+ LoadedConfig,
124
137
  } from "./config-editor.ts";
125
- export type { DecisionModelInput, DecisionModelPatch, LoadedConfig } from "./config-editor.ts";
126
138
  export {
127
139
  buildClassifierProviders,
128
140
  classifierBaseUrlNote,
129
141
  defaultDecisionModelName,
130
142
  directEndpointWouldClobber,
131
143
  } from "./classifier-catalog.ts";
144
+ export {
145
+ decisionModelConnection,
146
+ decisionModelsWithoutConnection,
147
+ referencedDecisionModelAddresses,
148
+ splitDecisionModelAddress,
149
+ } from "./classifier-connection.ts";
132
150
  export type {
133
151
  ClassifierModelSummary,
134
152
  ClassifierProviderOption,
package/src/types.ts CHANGED
@@ -31,17 +31,30 @@ export interface DecisionModelConfig {
31
31
  }
32
32
 
33
33
  /**
34
- * Connection details for one decision-model address - a `decisionModels:` map
35
- * value. `baseUrl` and `apiKey` come as a pair: a direct endpoint needs a bearer
36
- * token even when the endpoint ignores it (`apiKey: local`).
34
+ * Connection details for one classifier provider - a `decisionProviders:` map
35
+ * value, and also the shape of a per-address `decisionModels:` override.
36
+ * `baseUrl` and `apiKey` come as a pair: a direct endpoint needs a bearer token
37
+ * even when the endpoint ignores it (`apiKey: local`).
38
+ *
39
+ * The provider map is the normal place to put these: one entry serves every
40
+ * decision model of that provider (`ollama/tev1`, `ollama/tev1:0.8b`, ...), so a
41
+ * chain only names `provider/model` and no longer repeats endpoint details per
42
+ * model.
37
43
  */
38
- export interface DecisionModelEntry {
44
+ export interface DecisionProviderEntry {
39
45
  /** Direct SystemOne endpoint (http/https). */
40
46
  baseUrl?: string;
41
47
  /** Bearer token, or `secret:<name>`. Required with `baseUrl`. */
42
48
  apiKey?: string;
43
49
  }
44
50
 
51
+ /**
52
+ * Connection details for one decision-model address - a `decisionModels:` map
53
+ * value, and the per-address override that wins over `decisionProviders:`.
54
+ * Same shape as a provider entry; see `DecisionProviderEntry`.
55
+ */
56
+ export type DecisionModelEntry = DecisionProviderEntry;
57
+
45
58
  /**
46
59
  * A config entry after address resolution: `decisionModel` is always the
47
60
  * provider/id descriptor. This is what the router and the extension consume; the
@@ -51,11 +64,20 @@ export type ResolvedSwitchbackConfig = Omit<SwitchbackConfig, "decisionModel"> &
51
64
  decisionModel?: DecisionModelConfig;
52
65
  };
53
66
 
67
+ /** A classifier provider's connection details after secret resolution. */
68
+ export type DecisionProviderConfig = DecisionProviderEntry;
69
+
54
70
  /** A config file after aggregation and address resolution. */
55
71
  export interface ResolvedSwitchbackFileConfig {
56
72
  models: ResolvedSwitchbackConfig[];
57
73
  /** Resolved `decisionModels:` entries, keyed by their address. */
58
74
  decisionModels?: Record<DecisionModelId, DecisionModelConfig>;
75
+ /**
76
+ * Resolved `decisionProviders:` entries, keyed by provider id. Copied into
77
+ * every `models[].decisionModel` of that provider during resolution, so the
78
+ * router only ever reads a fully connected descriptor.
79
+ */
80
+ decisionProviders?: Record<string, DecisionProviderConfig>;
59
81
  debug?: boolean;
60
82
  }
61
83
 
@@ -75,9 +97,9 @@ export interface SwitchbackConfig {
75
97
  /** Ordered preference of physical models ("provider/id"). First entry is the preferred model. */
76
98
  fallbacks: ModelId[];
77
99
  /**
78
- * Decision model as "provider/model-id". Connection details for direct
79
- * endpoints live in the top-level `decisionModels:` map under the same
80
- * address. Absent: report and blind-cycle.
100
+ * Decision model as "provider/model-id". Connection details for a direct
101
+ * endpoint come from `decisionProviders:` (or a `decisionModels:` entry at
102
+ * this exact address, which wins). Absent: report and blind-cycle.
81
103
  */
82
104
  decisionModel?: DecisionModelId;
83
105
  /** Return to the head of the list after this much idle time (default `never`). */
@@ -88,9 +110,16 @@ export interface SwitchbackConfig {
88
110
  export interface SwitchbackFileConfig {
89
111
  models: SwitchbackConfig[];
90
112
  /**
91
- * Connection details for decision-model addresses that need a direct
92
- * SystemOne endpoint, keyed by the same "provider/model-id" address a chain
93
- * names in `decisionModel:`.
113
+ * Connection details for classifier providers that need a direct SystemOne
114
+ * endpoint, keyed by provider id. One entry covers every decision model of
115
+ * that provider, so `decisionModel: ollama/tev1` inherits
116
+ * `decisionProviders.ollama`. This is the normal place for endpoint + token.
117
+ */
118
+ decisionProviders?: Record<string, DecisionProviderEntry>;
119
+ /**
120
+ * Per-address connection overrides, keyed by "provider/model-id". Only needed
121
+ * when one model of a provider talks to a different endpoint than its
122
+ * provider entry; it wins over `decisionProviders:` for that address.
94
123
  */
95
124
  decisionModels?: Record<DecisionModelId, DecisionModelEntry>;
96
125
  /**