dsh-model-pool 0.0.0-stage → 0.1.0

package/lib/adapter.js

@@ -0,0 +1,151 @@
+/**
+ * The virtual provider adapter for `dsh-model-pool`.
+ *
+ * The adapter exists for one reason: `listProviders()` / `listModels()` /
+ * `resolveModelInfo()` are the only surfaces the composer picker and Settings
+ * read (`dsh-api-session-controller/lib/index.js:563-611`), and a route appears
+ * in them only when an `LlmAdapter` claims it. Actual dispatch never reaches
+ * this adapter — the `llm/stream` listener in `index.js` intercepts the request
+ * first and forwards it to a concrete provider.
+ *
+ * ## Why this does not extend `LlmAdapter`
+ *
+ * A profile bundle's `@deepseek-ai/dsh-llm` can resolve to a different physical
+ * copy (this profile links 0.1.7-rc.2 while the runtime is 0.2.1-rc.3), and the
+ * registry is duck-typed: `prepareRoutes` only calls `providerInfo()` and
+ * `providerRetryPolicy()`, and dispatch only calls `listModels()`,
+ * `resolveModel()`, `prepareCall()` and `stream()`. Implementing the surface
+ * directly removes a whole class of module-identity failure without weakening
+ * the contract.
+ *
+ * `stream()` is therefore a programming error, not a fallback: reaching it
+ * means the interceptor was not installed or named a different provider id.
+ *
+ * @module dsh-model-pool/lib/adapter
+ */
+
+/**
+ * Build a plain `Error` carrying the provider-neutral failure facts the runtime
+ * reads at its adapter boundary (`dsh-llm/lib/index.js:426-473`): an own
+ * `failure` snapshot whose `code` equals the own `code`.
+ * @param {string} message - human-readable summary.
+ * @param {string} code - stable machine-routable failure class.
+ * @returns {Error} the error to throw.
+ */
+function llmError(message, code) {
+  const error = new Error(message);
+  error.code = code;
+  error.failure = { message, code };
+  return error;
+}
+
+/**
+ * Adapter serving one virtual pool route.
+ */
+export class PoolAdapter {
+  /**
+   * @param {() => object} snapshotOf - live pool snapshot reader.
+   * @param {string} providerId - the virtual route this adapter owns.
+   * @param {string} providerName - display name for that route.
+   */
+  constructor(snapshotOf, providerId, providerName) {
+    this.snapshotOf = snapshotOf;
+    this.providerId = providerId;
+    this.providerName = providerName;
+  }
+
+  /**
+   * Describe the virtual route.
+   * @param {string} provider - the route passed to `registerAdapter()`.
+   * @returns {{ id: string, name: string }} display metadata.
+   */
+  providerInfo(provider) {
+    return { id: provider, name: this.providerName };
+  }
+
+  /**
+   * Use the runtime's normal retry policy.
+   * @returns {undefined} always, meaning "no route-specific policy".
+   */
+  providerRetryPolicy() {
+    return undefined;
+  }
+
+  /**
+   * Advertise one pool entry per logical model.
+   * @param {string} provider - the virtual route.
+   * @returns {Promise<object[]>} pool models as `LlmModelInfo` values.
+   */
+  async listModels(provider) {
+    const snapshot = this.snapshotOf();
+    return snapshot.models.map((model) => ({
+      provider,
+      id: model.id,
+      name: model.name,
+      ...model.description === undefined ? {} : { description: model.description },
+      ...model.inputModalities === undefined ? {} : { inputModalities: model.inputModalities },
+    }));
+  }
+
+  /**
+   * Resolve one pool entry to the union capability set.
+   *
+   * The pool advertises the union of its candidates' thinking depths, the union
+   * of their input modalities, and the minimum context window: a depth some
+   * candidate cannot serve stays selectable and the router maps it down to the
+   * nearest tier that candidate supports, the minimum window keeps the request
+   * inside every candidate's limit so failover cannot hit
+   * `CONTEXT_WINDOW_EXCEEDED`, and the modality union lets the resident pick a
+   * screenshot here instead of being told the model is text-only because one
+   * candidate happens to be. `lib/router.js` then honours the modality promise
+   * per request by skipping routes that cannot read the image.
+   *
+   * @param {string} provider - the virtual route.
+   * @param {string} model - pool model id.
+   * @returns {Promise<object>} resolved model info for the pool entry.
+   */
+  async resolveModel(provider, model) {
+    const snapshot = this.snapshotOf();
+    const entry = snapshot.models.find((candidate) => candidate.id === model);
+    if (entry === undefined) {
+      throw llmError(`model pool has no model "${model}"`, 'INVALID_MODEL_INFO');
+    }
+    return {
+      provider,
+      id: model,
+      name: entry.name,
+      ...entry.description === undefined ? {} : { description: entry.description },
+      ...entry.contextWindow === undefined ? {} : { context: { contextWindow: entry.contextWindow } },
+      ...entry.reasoning === undefined ? {} : { reasoning: entry.reasoning },
+      ...entry.inputModalities === undefined ? {} : { inputModalities: entry.inputModalities },
+      ...entry.systemPromptUpdate === undefined ? {} : { systemPromptUpdate: entry.systemPromptUpdate },
+    };
+  }
+
+  /**
+   * Bind one generation of pool metadata to the eventual dispatch.
+   * @param {string} provider - the virtual route.
+   * @param {string} model - pool model id.
+   * @param {AbortSignal} [signal] - cancellation for the metadata read.
+   * @returns {Promise<{ model: object, stream: (options: object) => AsyncIterable<object> }>} the call handle.
+   */
+  async prepareCall(provider, model, signal) {
+    return {
+      model: await this.resolveModel(provider, model, signal),
+      stream: (options) => this.stream(options),
+    };
+  }
+
+  /**
+   * Report that the interceptor did not run.
+   * @returns {AsyncIterable<never>} never yields; the throw becomes a terminal
+   *   `error` finish chunk at the runtime's adapter boundary.
+   */
+  async *stream() {
+    throw llmError(
+      `the model-pool route "${this.providerId}" was dispatched to its adapter; `
+        + 'the routing listener is not active, so no concrete provider was selected',
+      'NO_ADAPTER',
+    );
+  }
+}

package/lib/capabilities.js

@@ -0,0 +1,198 @@
+/**
+ * Input-modality capabilities for `dsh-model-pool`.
+ *
+ * A pool model is one logical model served by several concrete routes, and those
+ * routes do not always agree about what they accept. `deepseek-v4.1-flash` is
+ * served by four routes that take images and one (`deepseek-v4.1-flash-sg`) that
+ * does not, so a single answer is needed to two different questions:
+ *
+ * - **What may the user send?** The runtime gates attachment admission on the
+ *   *advertised* capability (`dsh-api-session-controller`: a prompt carrying an
+ *   image is refused with `MODEL_DOES_NOT_SUPPORT_IMAGES` when the resolved
+ *   `inputModalities` exists and omits `image`). Withholding `image` because
+ *   *one* candidate is text-only makes the pool reject an upload the majority of
+ *   its candidates handle natively. So the advertised set is the **union**: the
+ *   pool offers every modality at least one candidate accepts.
+ *
+ * - **Where may this call go?** The router must then honour that promise, so a
+ *   request carrying an image is only routed to routes that accept images. The
+ *   union is therefore paired with a per-request filter, and a call never lands
+ *   on a text-only route while an image-capable one is available.
+ *
+ * Undeclared capabilities stay undeclared. A route that reports no
+ * `inputModalities` is not evidence of anything, so the pool advertises
+ * `undefined` when *no* candidate declares a set (the runtime treats an absent
+ * set as "no constraint"), and treats an undeclared route as text-only when a
+ * request actually needs images.
+ *
+ * Pure: no I/O, no service access. Everything here is a function of its inputs.
+ *
+ * @module dsh-model-pool/lib/capabilities
+ */
+
+/** Modality id for text input. */
+export const TEXT = 'text';
+
+/** Modality id for image input. */
+export const IMAGE = 'image';
+
+/**
+ * Coerce one advertised modality list into a deduplicated string array.
+ *
+ * A route may hand back a frozen array, a plain array, or nothing at all. The
+ * result is always a fresh array, so a caller can never mutate a route's own
+ * metadata through the snapshot.
+ *
+ * @param {unknown} value - the raw `inputModalities` value.
+ * @returns {string[]|undefined} the modalities, or undefined when none were declared.
+ */
+export function normalizeModalities(value) {
+  if (!Array.isArray(value)) return undefined;
+  const out = [];
+  for (const entry of value) {
+    if (typeof entry !== 'string') continue;
+    const modality = entry.trim().toLowerCase();
+    if (modality === '' || out.includes(modality)) continue;
+    out.push(modality);
+  }
+  return out.length === 0 ? undefined : out;
+}
+
+/**
+ * The modalities one route is known to accept, with text as the floor.
+ *
+ * Text is implicit everywhere: every LLM route in the registry accepts text, and
+ * a route that advertises `['image']` alone still carries the text blocks that
+ * surround its images. Adding the floor keeps the filter below from ever
+ * classifying a route as unable to take a text-only call.
+ *
+ * @param {object} route - a pool route or a concrete model entry.
+ * @returns {string[]} accepted modalities, always including `text`.
+ */
+export function routeModalities(route) {
+  const declared = normalizeModalities(route?.inputModalities) ?? [];
+  return declared.includes(TEXT) ? declared : [TEXT, ...declared];
+}
+
+/**
+ * Whether one route accepts every modality a request needs.
+ *
+ * An undeclared route is text-only here on purpose: routing an image into a
+ * route whose capability is unknown risks the provider rejecting the whole
+ * call, while the reverse (treating it as capable) is exactly the bug this
+ * module exists to fix.
+ *
+ * @param {object} route - a pool route.
+ * @param {string[]} required - modalities the request carries.
+ * @returns {boolean} true when every required modality is accepted.
+ */
+export function routeServes(route, required) {
+  if (!Array.isArray(required) || required.length === 0) return true;
+  const accepted = routeModalities(route);
+  return required.every((modality) => accepted.includes(modality));
+}
+
+/**
+ * Fold the candidates' modalities into the set the pool advertises.
+ *
+ * The union, not the intersection: see the module comment. Duplicates are
+ * dropped and `text` is kept first so the advertised order reads naturally.
+ *
+ * @param {object[]} routes - pool routes with their per-route capabilities.
+ * @returns {string[]|undefined} the union, or undefined when no route declares one.
+ */
+export function foldInputModalities(routes) {
+  const declared = (Array.isArray(routes) ? routes : [])
+    .map((route) => normalizeModalities(route?.inputModalities))
+    .filter((value) => value !== undefined);
+  if (declared.length === 0) return undefined;
+  const union = [];
+  for (const modality of declared.flat()) {
+    if (!union.includes(modality)) union.push(modality);
+  }
+  // Text first and always present: it is the floor every route accepts, the
+  // client renders this set, and a pool advertising `['image']` alone would be
+  // nonsense even if every candidate happened to declare only that.
+  return [TEXT, ...union.filter((modality) => modality !== TEXT)];
+}
+
+/**
+ * Whether one content block array carries an image, walking tool results.
+ *
+ * Deliberately deeper than the shipped runtime's `contentHasImage`
+ * (`dsh-llm/lib/types/content.js` checks only top-level blocks): its image
+ * projection is shallow too, so a screenshot returned inside a tool result is
+ * never degraded for a text-only route — it reaches that adapter raw and some
+ * adapters reject images in non-user messages outright. Walking tool results
+ * here routes those calls to a route that can actually read the image. Repeated
+ * locally rather than imported because the pool is duck-typed against a possibly
+ * different physical copy of `@deepseek-ai/dsh-llm`.
+ *
+ * @param {unknown} content - one message's content blocks.
+ * @returns {boolean} true when an image block is present at any depth.
+ */
+export function contentHasImage(content) {
+  if (!Array.isArray(content)) return false;
+  for (const block of content) {
+    if (block === null || typeof block !== 'object') continue;
+    if (block.type === IMAGE) return true;
+    if (block.type === 'tool-result' && contentHasImage(block.content)) return true;
+  }
+  return false;
+}
+
+/**
+ * The modalities one request needs, derived from its messages.
+ *
+ * Only what the messages actually carry is required: a pool that advertises
+ * images must not refuse a text-only call, and a call with an image must not
+ * land on a route that cannot see it.
+ *
+ * @param {object[]} messages - the request messages (`{ role, content }`).
+ * @returns {string[]} required modalities, always including `text`.
+ */
+export function requiredModalities(messages) {
+  const required = [TEXT];
+  if (!Array.isArray(messages)) return required;
+  for (const message of messages) {
+    if (message === null || typeof message !== 'object') continue;
+    if (contentHasImage(message.content)) {
+      required.push(IMAGE);
+      break;
+    }
+  }
+  return required;
+}
+
+/**
+ * Keep only the routes that can serve this request.
+ *
+ * Never returns an empty list for a non-empty input: the requirement is a
+ * preference the pool has already promised the user it can honour, so when a
+ * stale snapshot or an over-tight filter leaves nothing capable, the unfiltered
+ * list is returned and the runtime's own projection degrades the image instead
+ * of failing the call outright.
+ *
+ * @param {object[]} routes - candidate routes.
+ * @param {string[]} required - modalities the request carries.
+ * @returns {object[]} capable routes, or the original list when none are capable.
+ */
+export function filterByModalities(routes, required) {
+  if (!Array.isArray(routes) || routes.length === 0) return Array.isArray(routes) ? routes : [];
+  const capable = routes.filter((route) => routeServes(route, required));
+  return capable.length > 0 ? capable : routes;
+}
+
+/**
+ * Whether an advertised modality set can take an image.
+ *
+ * Used by the client to render the pool-level capability badge without
+ * duplicating the `includes('image')` rule in two languages.
+ *
+ * @param {unknown} modalities - an advertised modality list.
+ * @returns {boolean} true when image input is advertised.
+ */
+export function acceptsImages(modalities) {
+  const normalized = normalizeModalities(modalities);
+  return normalized !== undefined && normalized.includes(IMAGE);
+}

package/lib/catalog.js

@@ -0,0 +1,175 @@
+/**
+ * Live-registry reader for `dsh-model-pool`.
+ *
+ * Enumerates every registered provider route and its models from the Host's
+ * `llm` service, then folds them into one pool snapshot through the pure
+ * grouping module. Per-provider failure isolation mirrors the shipped
+ * `buildModelCatalog` (`dsh-api-session-controller/lib/index.js:563-611`):
+ * one provider whose catalog throws must not hide the others.
+ *
+ * The reader also attaches the route-level capabilities the router and the
+ * virtual adapter need (`inputModalities`, `systemPromptUpdate`, `toolUpdate`)
+ * and folds them into pool-level aggregates. The fold is deliberately not uniform:
+ * a capability the Host gates on *before* the call exists (`inputModalities`) is
+ * the union so the pool does not look weaker than its candidates, while a
+ * protocol mode every route must agree on (`systemPromptUpdate`) stays
+ * conservative. See `lib/capabilities.js` for why.
+ *
+ * @module dsh-model-pool/lib/catalog
+ */
+
+import { buildPoolSnapshot } from './grouping.js';
+import { foldInputModalities } from './capabilities.js';
+
+/**
+ * Enumerate one provider's models and their resolved metadata.
+ * @param {object} llm - the live `llm` service.
+ * @param {{ id: string, name: string }} provider - one registered route.
+ * @returns {Promise<{ provider: object, models: object[] }>} enumerated models.
+ */
+async function enumerateProvider(llm, provider) {
+  const listed = await llm.listModels(provider.id);
+  const models = await Promise.all(
+    listed.map(async (model) => {
+      // `resolveModelInfo` is advisory: a route may advertise a model whose
+      // exact metadata query fails. Keep the model with the advertised facts
+      // rather than dropping it from the pool.
+      let resolved;
+      try {
+        resolved = await llm.resolveModelInfo(provider.id, model.id);
+      } catch {
+        resolved = undefined;
+      }
+      const reasoning = resolved?.reasoning;
+      const inputModalities = resolved?.inputModalities ?? model.inputModalities;
+      return {
+        id: model.id,
+        name: model.name,
+        ...model.description === undefined ? {} : { description: model.description },
+        ...reasoning === undefined ? {} : { reasoning },
+        ...resolved?.context?.contextWindow === undefined ? {} : { contextWindow: resolved.context.contextWindow },
+        ...inputModalities === undefined ? {} : { inputModalities: [...inputModalities] },
+        ...resolved?.systemPromptUpdate === undefined ? {} : { systemPromptUpdate: resolved.systemPromptUpdate },
+        ...resolved?.toolUpdate === undefined ? {} : { toolUpdate: resolved.toolUpdate },
+      };
+    }),
+  );
+  return { provider, models };
+}
+
+/**
+ * Fold a capability across every candidate route.
+ *
+ * - `inputModalities`: the **union**, so the pool offers every input at least one
+ *   candidate accepts. This is the capability the user is judged by: the runtime
+ *   refuses an image prompt outright when the advertised set omits `image`
+ *   (`dsh-api-session-controller: MODEL_DOES_NOT_SUPPORT_IMAGES`), so advertising
+ *   the intersection made a model whose majority routes read images reject every
+ *   upload because one candidate was text-only. The promise is kept by
+ *   `lib/router.js`, which routes an image call only to image-capable routes.
+ * - `systemPromptUpdate`: `'in-history'` only when every candidate declares it;
+ *   otherwise absent, which makes the loop emit a leading system message that
+ *   every route accepts.
+ *
+ * @param {object[]} routes - pool routes with their per-route capabilities.
+ * @returns {{ inputModalities?: string[], systemPromptUpdate?: string }} aggregates.
+ */
+function foldCapabilities(routes) {
+  const inputModalities = foldInputModalities(routes);
+  const inHistory = routes.length > 0 && routes.every((route) => route.systemPromptUpdate === 'in-history');
+  return {
+    ...inputModalities === undefined ? {} : { inputModalities },
+    ...inHistory ? { systemPromptUpdate: 'in-history' } : {},
+  };
+}
+
+/**
+ * Read the whole live registry into one pool snapshot.
+ *
+ * The virtual pool route itself is excluded: it must never become a candidate
+ * of another pool, which would let a pooled call route back into the pool.
+ *
+ * @param {object} llm - the live `llm` service.
+ * @param {object} config - plain pool configuration (see `docs/CONTRACT.md` §3.2).
+ * @param {string} selfProviderId - the virtual route this plugin owns.
+ * @returns {Promise<{ snapshot: object, failures: object[] }>} the pool snapshot.
+ */
+export async function readPoolSnapshot(llm, config, selfProviderId) {
+  const providers = llm
+    .listProviders()
+    .filter((provider) => provider.id !== selfProviderId);
+
+  const enumerated = await Promise.all(
+    providers.map(async (provider) => {
+      try {
+        return { kind: 'group', group: await enumerateProvider(llm, provider) };
+      } catch (error) {
+        return {
+          kind: 'failure',
+          failure: {
+            provider: provider.id,
+            name: provider.name,
+            message: error instanceof Error ? error.message : String(error),
+          },
+        };
+      }
+    }),
+  );
+
+  const groups = enumerated.flatMap((item) => (item.kind === 'group' ? [item.group] : []));
+  const failures = enumerated.flatMap((item) => (item.kind === 'failure' ? [item.failure] : []));
+
+  const built = buildPoolSnapshot(
+    {
+      // `grouping` takes the flat registry shape: `{ id, name, models }`.
+      providers: groups.map((group) => ({ ...group.provider, models: group.models })),
+      modelGroups: config.modelGroups,
+      providerOrder: config.providerOrder,
+      include: config.include,
+      exclude: config.exclude,
+      excludeModels: config.excludeModels,
+    },
+    failures,
+  );
+
+  // Route-level capability lookup, keyed by concrete provider + model.
+  const capabilities = new Map();
+  for (const group of groups) {
+    for (const model of group.models) {
+      capabilities.set(`${group.provider.id}\u0000${model.id}`, model);
+    }
+  }
+
+  const models = built.models.map((model) => {
+    const routes = model.routes.map((route) => {
+      const source = capabilities.get(`${route.provider}\u0000${route.model}`);
+      return {
+        ...route,
+        ...source?.inputModalities === undefined ? {} : { inputModalities: source.inputModalities },
+        ...source?.systemPromptUpdate === undefined ? {} : { systemPromptUpdate: source.systemPromptUpdate },
+        ...source?.toolUpdate === undefined ? {} : { toolUpdate: source.toolUpdate },
+      };
+    });
+    return { ...model, routes, ...foldCapabilities(routes) };
+  });
+
+  // The registry's own provider directory, in registration order. Settings uses
+  // it to offer every provider by name instead of asking for raw ids.
+  const directory = providers.map((provider, index) => ({
+    id: provider.id,
+    name: typeof provider.name === "string" && provider.name !== "" ? provider.name : provider.id,
+    registrationIndex: index,
+  }));
+
+  return {
+    snapshot: {
+      providerId: selfProviderId,
+      providerName: config.providerName,
+      providers: directory,
+      models,
+      failures: built.failures,
+      takenAt: Date.now(),
+    },
+    failures: built.failures,
+  };
+}

package/lib/effort.js

@@ -0,0 +1,151 @@
+/**
+* Reasoning-effort vocabulary and rank mapping shared by every pool route.
+* Pure: no I/O, no clocks, no randomness.
+* @module dsh-model-pool/lib/effort
+*/
+
+/** Canonical effort tiers, ascending. */
+export const EFFORT_RANK = ["off", "minimal", "low", "medium", "high", "max", "xhigh"];
+
+/**
+* Provider ids that mean the same tier under a different name.
+*
+* Adapters disagree on spelling: one advertises `off`, another calls the same
+* thing `disabled`. Without this alias table a pool that aggregates both would
+* offer two entries labelled "Off" and route each to a different wire value.
+*/
+const EFFORT_ALIASES = new Map([
+	// Observed in this deployment: one adapter advertises the off tier as `off`
+	// and another as `disabled`; both report the display name "Off".
+	["disabled", "off"],
+]);
+
+const RANKS = new Map(EFFORT_RANK.map((id, index) => [id, index]));
+
+/**
+* Canonical tier key for an effort id, folding aliases onto the canonical name.
+* @param id - effort id as advertised by a provider.
+* @returns the canonical tier id, or the trimmed lower-cased input when unknown.
+*/
+export function canonicalEffortId(id) {
+	if (typeof id !== "string") return "";
+	const key = id.trim().toLowerCase();
+	return EFFORT_ALIASES.get(key) ?? key;
+}
+
+/**
+* Canonical rank of an effort id.
+* @param id - effort id, matched case-insensitively.
+* @returns the ascending tier index, or -1 when the id is unknown.
+*/
+export function rankOf(id) {
+	if (typeof id !== "string") return -1;
+	return RANKS.get(canonicalEffortId(id)) ?? -1;
+}
+
+/**
+* Order efforts by canonical rank; unknown ids keep their relative order at the end.
+* @param efforts - efforts to order.
+* @returns a new ordered array; malformed entries are dropped.
+*/
+export function rankEfforts(efforts) {
+	const known = [];
+	const unknown = [];
+	for (const effort of Array.isArray(efforts) ? efforts : []) {
+		if (effort === null || typeof effort !== "object" || typeof effort.id !== "string") continue;
+		(rankOf(effort.id) < 0 ? unknown : known).push(effort);
+	}
+	known.sort((left, right) => rankOf(left.id) - rankOf(right.id));
+	return [...known, ...unknown];
+}
+
+/**
+* Union several effort lists by id.
+* @param lists - effort lists in candidate order.
+* @returns the ranked union; the first occurrence of an id wins its name and description.
+*/
+export function unionEfforts(lists) {
+	// Deduplicate by canonical tier, not raw id: two providers naming the same
+	// tier differently (`off` / `disabled`) must collapse into one entry, or the
+	// picker shows the label twice.
+	const byTier = new Map();
+	for (const list of Array.isArray(lists) ? lists : []) {
+		for (const effort of Array.isArray(list) ? list : []) {
+			if (effort === null || typeof effort !== "object" || typeof effort.id !== "string") continue;
+			const tier = canonicalEffortId(effort.id);
+			if (tier === "") continue;
+			if (!byTier.has(tier)) byTier.set(tier, effort);
+		}
+	}
+	return rankEfforts([...byTier.values()]);
+}
+
+/**
+* Map a requested effort onto the nearest tier a target route supports.
+* Exact matches win; otherwise the smallest rank distance wins and ties go to the
+* higher tier.
+* @param targetEfforts - the concrete target route's efforts.
+* @param requestedId - the effort requested for the pooled model.
+* @returns the chosen target effort id, or undefined when the target has no efforts
+* or the request is missing/unknown.
+*/
+export function pickEffort(targetEfforts, requestedId) {
+	const efforts = (Array.isArray(targetEfforts) ? targetEfforts : []).filter(
+		(effort) => effort !== null && typeof effort === "object" && typeof effort.id === "string",
+	);
+	if (efforts.length === 0) return undefined;
+	if (typeof requestedId !== "string" || requestedId.trim() === "") return undefined;
+	const wanted = requestedId.trim();
+	const wantedTier = canonicalEffortId(wanted);
+	// Match on the canonical tier, not the raw spelling: a route advertising
+	// `disabled` satisfies a request for `off`, and vice versa. Returning that
+	// route's own id keeps the wire value legal for it.
+	const exact = efforts.find((effort) => effort.id === wanted || canonicalEffortId(effort.id) === wantedTier);
+	if (exact !== undefined) return exact.id;
+	const wantedRank = rankOf(wanted);
+	if (wantedRank < 0) return undefined;
+
+	// `off` means "do not reason". A route with no off tier cannot honour that,
+	// and rounding it up to `medium`/`high` would silently spend more reasoning
+	// than asked. Fall back to that route's cheapest tier instead — the closest
+	// thing it has to "off" — so the adjustment is always toward less work.
+	if (wantedTier === "off") {
+		let cheapest;
+		for (const effort of efforts) {
+			const rank = rankOf(effort.id);
+			if (rank < 0) continue;
+			if (cheapest === undefined || rank < rankOf(cheapest.id)) cheapest = effort;
+		}
+		if (cheapest !== undefined) return cheapest.id;
+	}
+	let best;
+	let bestDistance = Infinity;
+	for (const effort of efforts) {
+		const rank = rankOf(effort.id);
+		if (rank < 0) continue;
+		const distance = Math.abs(rank - wantedRank);
+		if (distance < bestDistance || (distance === bestDistance && (best === undefined || rank > rankOf(best.id)))) {
+			best = effort;
+			bestDistance = distance;
+		}
+	}
+	return best?.id;
+}
+
+/**
+* Whether an effort list contains an id.
+* @param efforts - efforts to search.
+* @param id - effort id, matched case-insensitively.
+* @returns true when a matching effort exists.
+*/
+export function isSupported(efforts, id) {
+	if (typeof id !== "string") return false;
+	const wanted = id.trim().toLowerCase();
+	return (Array.isArray(efforts) ? efforts : []).some(
+		(effort) =>
+			effort !== null &&
+			typeof effort === "object" &&
+			typeof effort.id === "string" &&
+			effort.id.trim().toLowerCase() === wanted,
+	);
+}