Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

fix(routing): exclude contributor wire ids unless typed exactly

Jack Rudenko13d4e691e430
diff --git a/packages/cli/src/model-loader.ts b/packages/cli/src/model-loader.ts
index 6a24e1b1..630d3b8c 100644
--- a/packages/cli/src/model-loader.ts
+++ b/packages/cli/src/model-loader.ts
@@ -16,6 +16,7 @@ import {
parseCatalogV3Envelope,
} from "./providers/catalog-v3.js";
import type { ConnectionWire } from "./providers/connection-wire.js";
+import { normaliseCatalogPayload } from "./providers/content-use.js";
import { compareByReleaseDateDesc } from "./providers/model-ordering.js";
import type { OpenRouterModel } from "./types.js";
@@ -131,6 +132,13 @@ export interface RecommendedSubscriptionRoute {
export interface RecommendedModelsDoc {
contractVersion?: 3;
generationId?: string;
+ /**
+ * claudish's own projection version ({@link RECOMMENDED_PROJECTION_VERSION}).
+ * A disk cache written by an older projection is rebuilt even within its
+ * generation: the `command` it holds may name a wire id the current rules
+ * would never choose.
+ */
+ projectionVersion?: number;
version: string;
lastUpdated: string;
generatedAt?: string;
@@ -348,6 +356,13 @@ let _cachedRecommendedModels: RecommendedModelsDoc | null = null;
const FIREBASE_BASE_URL = "https://us-central1-claudish-6da10.cloudfunctions.net/queryModels";
const FIREBASE_RECOMMENDED_URL = `${FIREBASE_BASE_URL}?catalog=recommended`;
+/**
+ * Bumped when {@link projectRecommendations} would answer differently for the
+ * same generation. 1: content-use opt-in wire ids are never a `command`
+ * (`content-use.ts`); a projection written before that may hold one.
+ */
+export const RECOMMENDED_PROJECTION_VERSION = 1;
+
/**
* The projected recommended-models list, on disk.
*
@@ -383,7 +398,9 @@ async function fetchCatalogPage<T>(
if (generationId && envelope.generationId !== generationId) {
throw new Error("Model catalog generation changed during the read");
}
- return envelope;
+ // Every Firebase `ModelDoc` read passes through here, so this is where their
+ // content-use opt-in connections are set aside (`content-use.ts`).
+ return { ...envelope, data: normaliseCatalogPayload(envelope.data) };
}
async function fetchCatalogData<T>(
@@ -552,6 +569,7 @@ export function projectRecommendations(
return {
contractVersion: 3,
generationId: recommendations.generationId,
+ projectionVersion: RECOMMENDED_PROJECTION_VERSION,
version: recommendations.generationId,
lastUpdated: stamp,
generatedAt: stamp,
@@ -728,6 +746,13 @@ function readRecommendedModelsCacheFile(): RecommendedModelsDoc | null {
} catch {
return null;
}
+ // A projection an older build wrote within this same generation may hold a
+ // `command` the current rules would never choose (a content-use opt-in wire
+ // id): rebuild it. Checked on the DISK copy only — the doc reader itself
+ // judges shape, and a freshly projected doc always carries this version.
+ if (!isRecord(parsed) || parsed.projectionVersion !== RECOMMENDED_PROJECTION_VERSION) {
+ return null;
+ }
return readProjectedRecommendationsDoc(parsed);
}
diff --git a/packages/cli/src/providers/all-models-cache.ts b/packages/cli/src/providers/all-models-cache.ts
index ec9bbc67..8abc3455 100644
--- a/packages/cli/src/providers/all-models-cache.ts
+++ b/packages/cli/src/providers/all-models-cache.ts
@@ -10,6 +10,7 @@ import {
registryVersionAtLeast,
routeProfile,
} from "./connection-wire.js";
+import { allConnections, splitOptInConnections } from "./content-use.js";
export type ReasoningControl = "toggle" | "effort" | "adaptive" | "budget" | "none";
@@ -58,6 +59,13 @@ export interface SlimModelEntry {
/** What the model produces. Absent, null or [] means unknown; a list without "text" is not a chat model. */
outputModalities?: string[] | null;
aggregators?: AggregatorEntry[];
+ /**
+ * Connections whose wire id opts content into the vendor's product
+ * improvement, moved out of `aggregators` when the catalog is read into memory
+ * (`splitOptInConnections`, `content-use.ts`). Never written to disk. Only an
+ * exact-id reader looks here (`allConnections`); nothing chooses one for a user.
+ */
+ optInConnections?: AggregatorEntry[];
subscriptionPlanIds?: string[];
tokenParam?: string;
routeVariant?: RouteVariant;
@@ -182,8 +190,10 @@ export function wiresMatchRegistry(
if (routeRegistry.generationId !== catalogGenerationId) return false;
const { registry } = routeRegistry;
if (!registryVersionAtLeast(registry.registryVersion, WIRE_REGISTRY_VERSION)) return true;
+ // Every row, opt-in included: an explicit contributor request builds from its
+ // own connection's wire, so that wire is validated like any other.
return entries.every((entry) =>
- (entry.aggregators ?? []).every((connection) => {
+ allConnections(entry).every((connection) => {
if (connection.routeStatus !== "mapped") return true;
if (!connection.route || !isConnectionWire(connection.wire)) return false;
const profile = routeProfile(registry, connection.route);
@@ -296,6 +306,11 @@ export function readAllModelsCache(path: string = ALL_MODELS_CACHE_PATH): DiskCa
cache = { ...cache, routeRegistry: registry };
}
}
+ // Validated RAW above (the parse and the sidecar attach both see every row),
+ // then split here, before any reader can see it. This is the choke point that
+ // keeps a content-use opt-in wire id from being chosen for a user
+ // (`content-use.ts`).
+ if (cache) cache = { ...cache, entries: cache.entries.map(splitOptInConnections) };
_readMemo.set(path, { key, cache });
return cache;
}
diff --git a/packages/cli/src/providers/catalog-client.ts b/packages/cli/src/providers/catalog-client.ts
index 5ca96236..211dec98 100644
--- a/packages/cli/src/providers/catalog-client.ts
+++ b/packages/cli/src/providers/catalog-client.ts
@@ -16,6 +16,7 @@ import {
type RouteRegistry,
isRouteRegistry,
} from "./connection-wire.js";
+import { allConnections, splitOptInConnections } from "./content-use.js";
import { _clearChatCapabilityIndex } from "./transport/probe-discovery.js";
const DEFAULT_CATALOG_URL =
@@ -114,7 +115,9 @@ export function isCatalogWarm(): boolean {
}
export function _setCatalogEntriesForTest(entries: SlimModelEntry[] | null): void {
- _catalogEntriesForTest = entries;
+ // The same normalisation as every other way entries reach memory, so a test
+ // seeds exactly what production reads (`content-use.ts`).
+ _catalogEntriesForTest = entries ? entries.map(splitOptInConnections) : entries;
}
export function _resetCatalogClient(): void {
@@ -123,8 +126,9 @@ export function _resetCatalogClient(): void {
_warmPromise = null;
}
+/** Every wire id the entry publishes, opt-in included: an exact reverse lookup. */
function allExternalIds(entry: SlimModelEntry): string[] {
- return (entry.aggregators ?? []).flatMap((connection) =>
+ return allConnections(entry).flatMap((connection) =>
typeof connection.externalModelId === "string" ? [connection.externalModelId] : []
);
}
@@ -166,6 +170,16 @@ export function externalIdFor(entry: SlimModelEntry, provider: string): string |
return wireIds.find((wireId) => !isMovingPointer(wireId)) ?? null;
}
+/** Whether `entry` maps `wireId` exactly on a route bound to `provider`, opt-in rows included. */
+function publishesWireIdFor(entry: SlimModelEntry, provider: string, wireId: string): boolean {
+ return allConnections(entry).some(
+ (connection) =>
+ connection.routeStatus === "mapped" &&
+ connection.externalModelId === wireId &&
+ catalogRouteMatchesProvider(connection.route, provider)
+ );
+}
+
export function resolveExternalId(
userInput: string,
provider: string,
@@ -179,6 +193,12 @@ export function resolveExternalId(
}
if (!entries) return null;
+ // An id this provider publishes, typed exactly, is its own answer — opt-in
+ // rows included. This is how `[email protected]` is sent
+ // verbatim: every step below CHOOSES a wire id, and a chosen one is never a
+ // content-use opt-in (`content-use.ts`).
+ if (entries.some((entry) => publishesWireIdFor(entry, provider, userInput))) return userInput;
+
const byModelId = entries.find((entry) => entry.modelId === userInput);
if (byModelId) return externalIdFor(byModelId, provider);
@@ -447,7 +467,10 @@ async function refreshCatalogOnce(
return { kind: "fetch_failed", reason: "incomplete" };
}
- const models = entries.flatMap((entry) => {
+ // The disk keeps the RAW rows (validated above, and what older builds read);
+ // memory gets them split, exactly as `readAllModelsCache` hands them out.
+ const normalised = entries.map(splitOptInConnections);
+ const models = normalised.flatMap((entry) => {
const id = externalIdFor(entry, "openrouter");
return id ? [{ id }] : [];
});
@@ -469,7 +492,7 @@ async function refreshCatalogOnce(
// withholds models the refresh just described. Its doc comment already said
// "after a catalog refresh" — nothing had ever called it.
_clearChatCapabilityIndex();
- _memCache = entries;
+ _memCache = normalised;
_warmPromise = Promise.resolve();
return {
kind: "refreshed",
diff --git a/packages/cli/src/providers/connection-resolver.ts b/packages/cli/src/providers/connection-resolver.ts
index 877bfd8c..04b2f059 100644
--- a/packages/cli/src/providers/connection-resolver.ts
+++ b/packages/cli/src/providers/connection-resolver.ts
@@ -24,6 +24,7 @@ import {
routeProfile,
wireRequestUrl,
} from "./connection-wire.js";
+import { allConnections } from "./content-use.js";
export interface ResolvedConnection {
/** The claudish provider the request is for. */
@@ -79,8 +80,11 @@ function stripVendorPrefix(id: string): string {
return id.includes("/") ? id.substring(id.lastIndexOf("/") + 1) : id;
}
-function mappedOnRoute(entry: SlimModelEntry, route: CatalogRouteBinding): AggregatorEntry[] {
- return (entry.aggregators ?? []).filter(
+function mappedOnRoute(
+ connections: AggregatorEntry[],
+ route: CatalogRouteBinding
+): AggregatorEntry[] {
+ return connections.filter(
(connection) =>
connection.routeStatus === "mapped" &&
connection.route?.routeId === route.routeId &&
@@ -94,9 +98,12 @@ function mappedOnRoute(entry: SlimModelEntry, route: CatalogRouteBinding): Aggre
*
* 1. A connection whose wire id IS the name: an explicit spec is rewritten to
* the provider's wire id before it gets here (`kc@k3`, `or@openai/gpt-6.1-sol`).
+ * Opt-in rows included, so an explicit `[email protected]`
+ * gets ITS connection and wire (`content-use.ts`).
* 2. The record whose canonical id or alias is the name (vendor prefix
* dropped), then its exact wire id on that route — never a moving pointer
- * unless the model's own id is one (same rule as `externalIdFor`).
+ * unless the model's own id is one (same rule as `externalIdFor`), and never
+ * a content-use opt-in id, since this step chooses one.
*/
function findConnection(
entries: SlimModelEntry[],
@@ -104,7 +111,9 @@ function findConnection(
modelName: string
): { entry: SlimModelEntry; connection: AggregatorEntry } | undefined {
for (const entry of entries) {
- const connection = mappedOnRoute(entry, route).find((c) => c.externalModelId === modelName);
+ const connection = mappedOnRoute(allConnections(entry), route).find(
+ (c) => c.externalModelId === modelName
+ );
if (connection) return { entry, connection };
}
@@ -117,7 +126,7 @@ function findConnection(
candidate.aliases.some((alias) => lower(alias) === name || lower(alias) === bare)
);
if (!entry) return undefined;
- const connections = mappedOnRoute(entry, route);
+ const connections = mappedOnRoute(entry.aggregators ?? [], route);
const connection = isMovingPointer(entry.modelId)
? connections[0]
: connections.find((c) => !isMovingPointer(c.externalModelId as string));
diff --git a/packages/cli/src/providers/content-use.ts b/packages/cli/src/providers/content-use.ts
new file mode 100644
index 00000000..d8ac0f48
--- /dev/null
+++ b/packages/cli/src/providers/content-use.ts
@@ -0,0 +1,109 @@
+/**
+ * Content-use opt-in wire ids, and the one place they are set aside.
+ *
+ * Some vendors publish a second wire id for one model whose use opts the
+ * request's CONTENT into the vendor's product improvement:
+ * `muse-spark-1.3-contributor` beside `muse-spark-1.3` on Meta's API, and
+ * `…-contributor-free` beside the plain id on OpenCode Zen. The catalog maps
+ * both as ordinary connections, so every reader that chooses a wire id for the
+ * user (`externalIdFor`, the gatherer, a plan's wire id, the picker, a probe
+ * pick) could choose the contributor one, and sometimes did: on generation
+ * `g-20261015133900604-fb6199b5` OpenCode Go mapped only the contributor id for
+ * `muse-spark-1.3`, so a bare `muse-spark-1.3` went to Go first, opted in.
+ *
+ * The project owner's decision (2026-10-16): a contributor id is NEVER chosen
+ * implicitly, on any route. A user who types one exactly
+ * (`[email protected]`) gets it verbatim.
+ *
+ * Enforced where catalog data enters memory, not at each reader: every reader
+ * found by `grep -rn aggregators` sits downstream of one of these points, and a
+ * reader added later inherits the rule without knowing it exists.
+ *
+ * - the slim catalog read from disk (`readAllModelsCache`) and the one just
+ * fetched (`refreshCatalog`, `_setCatalogEntriesForTest`) — {@link splitOptInConnections};
+ * - Firebase `ModelDoc`s (`fetchCatalogPage`) — {@link normaliseCatalogPayload};
+ * - hosted probe picks (`getProbeModel`), endpoint probe picks
+ * (`rankProbeCandidates`), dynamic models catalogs
+ * (`discoverProviderModelsCatalog`) and a resolver's expansion
+ * (`expandSelection`) — {@link isOptInWireId} directly.
+ *
+ * The opt-in rows are not deleted. They move to `optInConnections`, and only an
+ * EXACT-id reader looks there ({@link allConnections}): the explicit-spec wire
+ * lookup, `findConnection`'s exact step, the availability reverse lookup and the
+ * registry validation.
+ *
+ * This is the ONE wire-id name rule claudish keeps. It is removed when the
+ * catalog publishes a content-use field on every route (models-index M3).
+ */
+import type { AggregatorEntry } from "../model-loader.js";
+
+/**
+ * A wire id that opts the request's content into the vendor's product-improvement use.
+ * Replace with the catalog field when models-index publishes one (M3, every route).
+ */
+export function isOptInWireId(wireId: string): boolean {
+ return /-contributor(?:-free)?$/i.test(wireId.split("/").pop() ?? wireId);
+}
+
+/** Whether one catalog connection's wire id opts content in. */
+function isOptInConnection(connection: AggregatorEntry): boolean {
+ return (
+ typeof connection.externalModelId === "string" && isOptInWireId(connection.externalModelId)
+ );
+}
+
+/**
+ * The entry with its opt-in connections moved from `aggregators` to
+ * `optInConnections`. Idempotent: an entry already split, or one with no opt-in
+ * row, is returned unchanged (the same object), so a second pass costs nothing
+ * and never loses the rows the first pass moved.
+ */
+export function splitOptInConnections<T extends { aggregators?: AggregatorEntry[] | null }>(
+ entry: T
+): T & { optInConnections?: AggregatorEntry[] } {
+ const aggregators = entry.aggregators;
+ if (!Array.isArray(aggregators) || !aggregators.some(isOptInConnection)) return entry;
+ const existing = (entry as { optInConnections?: AggregatorEntry[] }).optInConnections ?? [];
+ return {
+ ...entry,
+ aggregators: aggregators.filter((connection) => !isOptInConnection(connection)),
+ optInConnections: [...existing, ...aggregators.filter(isOptInConnection)],
+ };
+}
+
+/**
+ * Every connection of an entry, opt-in rows included. For EXACT-id readers only:
+ * a lookup that matches the wire id the user typed, or that validates every row.
+ * A reader that CHOOSES a wire id reads `aggregators`, never this.
+ */
+export function allConnections(entry: {
+ aggregators?: AggregatorEntry[] | null;
+ optInConnections?: AggregatorEntry[];
+}): AggregatorEntry[] {
+ return [...(entry.aggregators ?? []), ...(entry.optInConnections ?? [])];
+}
+
+/**
+ * {@link splitOptInConnections} over a catalog payload whose `models` array or
+ * `model` object carries `ModelDoc`s. Any other payload (providers list,
+ * recommendations) is returned unchanged.
+ */
+export function normaliseCatalogPayload<T>(data: T): T {
+ if (!data || typeof data !== "object") return data;
+ const payload = data as Record<string, unknown>;
+ let changed = false;
+ const next: Record<string, unknown> = { ...payload };
+ if (Array.isArray(payload.models)) {
+ next.models = payload.models.map((model) =>
+ model && typeof model === "object"
+ ? splitOptInConnections(model as { aggregators?: AggregatorEntry[] })
+ : model
+ );
+ changed = true;
+ }
+ if (payload.model && typeof payload.model === "object") {
+ next.model = splitOptInConnections(payload.model as { aggregators?: AggregatorEntry[] });
+ changed = true;
+ }
+ return (changed ? next : data) as T;
+}
diff --git a/packages/cli/src/providers/model-availability.ts b/packages/cli/src/providers/model-availability.ts
index a38a0b7f..5e75f686 100644
--- a/packages/cli/src/providers/model-availability.ts
+++ b/packages/cli/src/providers/model-availability.ts
@@ -45,9 +45,10 @@ import { catalogRouteMatchesProvider } from "./catalog-route-bindings.js";
*/
import { getCatalogEntries } from "./catalog-client.js";
+import { allConnections } from "./content-use.js";
import {
type DiscoveredModel,
- discoverProviderModels,
+ discoverProviderServedIds,
getDiscoveryFailure,
} from "./model-discovery.js";
import { expandSelection } from "./model-resolvers/registry.js";
@@ -118,7 +119,11 @@ export async function providerServesModel(
// than what the vendor offers in general.
const def = getProviderByName(provider);
if (def?.modelDiscovery) {
- const models = await discoverProviderModels(provider);
+ // BOTH lists: this answers whether the id the request carries is entitled,
+ // and an explicitly typed content-use opt-in id is entitled when the account
+ // serves it. Nothing here offers a model, so nothing here can choose one.
+ const { served, optIn } = await discoverProviderServedIds(provider);
+ const models = [...served, ...optIn];
if (models.length > 0) {
return modelsCatalogHas(
models.map((m) => m.id),
@@ -159,11 +164,12 @@ export async function providerServesModel(
(e) =>
e.modelId.toLowerCase() === needle ||
e.aliases.some((a) => a.toLowerCase() === needle) ||
- (e.aggregators ?? []).some((a) => a.externalModelId?.toLowerCase() === needle)
+ allConnections(e).some((a) => a.externalModelId?.toLowerCase() === needle)
);
if (!row) return "unknown";
- return (row.aggregators ?? []).some(
+ // Exact reverse lookup, opt-in rows included: it confirms, it never chooses.
+ return allConnections(row).some(
(a) => a.routeStatus === "mapped" && catalogRouteMatchesProvider(a.route, provider)
)
? "serves"
diff --git a/packages/cli/src/providers/model-discovery.ts b/packages/cli/src/providers/model-discovery.ts
index a784d2ba..59da69b8 100644
--- a/packages/cli/src/providers/model-discovery.ts
+++ b/packages/cli/src/providers/model-discovery.ts
@@ -30,6 +30,7 @@ import { credentials } from "../auth/credentials/authority.js";
import { log } from "../logger.js";
import { VERSION } from "../version.js";
import { resolveRouteProfile } from "./connection-resolver.js";
+import { isOptInWireId } from "./content-use.js";
import { compareByReleaseDateDesc } from "./model-ordering.js";
import type { ModelOffer, ModelsCatalogAxis, ModelsCatalogEntry } from "./model-resolvers/types.js";
import { getProviderByName } from "./provider-definitions.js";
@@ -290,7 +291,17 @@ export interface DiscoveryFailure {
* fault the user can fix, so it is `failed{unreachable}` naming the variable.
*/
export type ModelsCatalogOutcome =
- | { kind: "served"; models: DiscoveredModel[] }
+ | {
+ kind: "served";
+ /** The models claudish may offer or pick: content-use opt-in ids excluded. */
+ models: DiscoveredModel[];
+ /**
+ * Opt-in wire ids the account also serves (`content-use.ts`). Never offered
+ * or picked; read only to confirm an id the user typed exactly. Absent when
+ * there are none.
+ */
+ optInIds?: string[];
+ }
| { kind: "failed"; failure: DiscoveryFailure }
| { kind: "unsupported"; reason: "no-descriptor" | "no-fetcher" };
@@ -644,6 +655,37 @@ async function discoverViaFetcher(
export async function discoverProviderModelsCatalog(
providerName: string
): Promise<ModelsCatalogOutcome> {
+ const outcome = await discoverEveryServedModel(providerName);
+ if (outcome.kind !== "served") return outcome;
+ // The single discovery entry, so this is the choke point for dynamic models
+ // catalogs: everything that offers or picks a model reads `models`, and a
+ // content-use opt-in id is never one of them (`content-use.ts`).
+ const models = outcome.models.filter((model) => !isOptInWireId(model.id));
+ if (models.length === outcome.models.length) return outcome;
+ const optInIds = outcome.models.filter((model) => isOptInWireId(model.id)).map((m) => m.id);
+ return { kind: "served", models, optInIds };
+}
+
+/**
+ * Every model the account serves, opt-in ids included, for the EXACT-id readers:
+ * whether a typed id is entitled (`providerServesModel`) and its served window
+ * (`discoverContextWindow`). `optIn` holds the content-use opt-in ids, which
+ * nothing may offer or pick. Fail-soft like {@link discoverProviderModels}: both
+ * lists are empty on any failure. Shares the one discovery cache.
+ */
+export async function discoverProviderServedIds(
+ providerName: string
+): Promise<{ served: DiscoveredModel[]; optIn: DiscoveredModel[] }> {
+ const outcome = await discoverEveryServedModel(providerName);
+ if (outcome.kind !== "served") return { served: [], optIn: [] };
+ return {
+ served: outcome.models.filter((model) => !isOptInWireId(model.id)),
+ optIn: outcome.models.filter((model) => isOptInWireId(model.id)),
+ };
+}
+
+/** The discovery itself: the full list the provider returned, cached unsplit. Never rejects. */
+async function discoverEveryServedModel(providerName: string): Promise<ModelsCatalogOutcome> {
const cached = _cache.get(providerName);
if (cached && cached.expiresAt > Date.now()) return { kind: "served", models: cached.models };
@@ -833,8 +875,9 @@ export async function discoverContextWindow(
providerName: string,
modelId: string
): Promise<number | undefined> {
- const models = await discoverProviderModels(providerName);
- const match = models.find((m) => m.id.toLowerCase() === modelId.toLowerCase());
+ // Exact-id lookup: an opt-in id the user typed still gets its served window.
+ const { served, optIn } = await discoverProviderServedIds(providerName);
+ const match = [...served, ...optIn].find((m) => m.id.toLowerCase() === modelId.toLowerCase());
return match?.contextWindow;
}
diff --git a/packages/cli/src/providers/model-resolvers/registry.ts b/packages/cli/src/providers/model-resolvers/registry.ts
index 1b0c1db1..8a98de15 100644
--- a/packages/cli/src/providers/model-resolvers/registry.ts
+++ b/packages/cli/src/providers/model-resolvers/registry.ts
@@ -10,6 +10,7 @@
* Only a provider that encodes knobs INTO its model ids needs an entry here.
*/
+import { isOptInWireId } from "../content-use.js";
import { DevinModelResolver } from "./devin.js";
import type {
ExpandContext,
@@ -70,5 +71,11 @@ export function expandSelection(
modelsCatalog: ModelsCatalogEntry[],
ctx: ExpandContext = {}
): string {
- return getModelResolver(provider)?.expand(selection, modelsCatalog, ctx) ?? selection;
+ // A resolver CHOOSES among the account's wire ids, so it never sees a
+ // content-use opt-in id unless the selection is one, typed exactly
+ // (`content-use.ts`). Devin's list reaches here without passing discovery.
+ const eligible = isOptInWireId(selection)
+ ? modelsCatalog
+ : modelsCatalog.filter((entry) => !isOptInWireId(entry.wireId));
+ return getModelResolver(provider)?.expand(selection, eligible, ctx) ?? selection;
}
diff --git a/packages/cli/src/providers/probe-catalog.ts b/packages/cli/src/providers/probe-catalog.ts
index 9e23a3a9..ef5d7316 100644
--- a/packages/cli/src/providers/probe-catalog.ts
+++ b/packages/cli/src/providers/probe-catalog.ts
@@ -3,6 +3,7 @@ import { homedir } from "node:os";
import { dirname, join } from "node:path";
import { catalogReadProvidersForRoute } from "./catalog-route-bindings.js";
import { CATALOG_V3_ACCEPT, parseCatalogV3Envelope } from "./catalog-v3.js";
+import { isOptInWireId } from "./content-use.js";
const PROBE_MODELS_URL = "https://us-central1-claudish-6da10.cloudfunctions.net/probeModels";
const CACHE_TTL_MS = 60 * 60 * 1000;
@@ -205,9 +206,16 @@ async function fetchAndCacheProbeModels(): Promise<FetchOutcome> {
return outcome;
}
+/**
+ * The hosted probe pick for a provider, or null.
+ *
+ * Null for a content-use opt-in wire id as well (`content-use.ts`): a probe is
+ * a request claudish chooses to send, and it never opts the user's content in.
+ * The caller then asks the endpoint's own list, which applies the same rule.
+ */
export function getProbeModel(claudishSlug: string): string | null {
const value = readProbeModelsCache()?.providers[claudishSlug];
- return typeof value === "string" && value.length > 0 ? value : null;
+ return typeof value === "string" && value.length > 0 && !isOptInWireId(value) ? value : null;
}
export function getProbeUnavailability(claudishSlug: string): string | null {
diff --git a/packages/cli/src/providers/probe-runner.ts b/packages/cli/src/providers/probe-runner.ts
index a821bbc3..8ab19e52 100644
--- a/packages/cli/src/providers/probe-runner.ts
+++ b/packages/cli/src/providers/probe-runner.ts
@@ -29,6 +29,7 @@ export const DROPPED_LABEL: Record<DroppedOutcome, string> = {
"credential-unreadable": "credential could not be read",
"not-served": "account does not serve it",
"excluded-by-membership": "not in the plan's membership",
+ "excluded-by-content-use": "contributor id: content-use opt-in, type it exactly to use it",
};
/**
diff --git a/packages/cli/src/providers/route-candidates.ts b/packages/cli/src/providers/route-candidates.ts
index 0c95ee84..46f06dd1 100644
--- a/packages/cli/src/providers/route-candidates.ts
+++ b/packages/cli/src/providers/route-candidates.ts
@@ -70,8 +70,9 @@
* identical inputs, and the reason would live nowhere a user could see.
*/
+import type { AggregatorEntry } from "../model-loader.js";
import { type SlimModelEntry, readAllModelsCache } from "./all-models-cache.js";
-import { externalIdFor, getCatalogEntries } from "./catalog-client.js";
+import { externalIdFor, getCatalogEntries, isMovingPointer } from "./catalog-client.js";
import {
CATALOG_ROUTE_BINDINGS,
type CatalogRouteBinding,
@@ -104,8 +105,31 @@ export interface RouteCandidate {
source: "catalog-connection" | "namespace-claim";
}
+/**
+ * Why the gatherer set a candidate aside instead of returning it. Each names a
+ * `CandidateOutcome` (`routing-rules.ts`), so a display can show the drop.
+ *
+ * - `excluded-by-content-use`: the provider maps the model only through a
+ * content-use opt-in wire id, which claudish never chooses (`content-use.ts`).
+ */
+export type GatheringExclusion = "excluded-by-content-use";
+
+/** A candidate the catalog publishes and the gatherer did not keep, with why. */
+export interface ExcludedCandidate {
+ candidate: RouteCandidate;
+ outcome: GatheringExclusion;
+}
+
export interface CandidateGathering {
+ /** The candidates a routing chain may use, ordered. Never contains an excluded one. */
candidates: RouteCandidate[];
+ /**
+ * Candidates set aside before any credential is read, ordered like
+ * `candidates`. Kept apart so the only consumer, `explainCatalogChain`, can
+ * show each one with its outcome and never mark it `kept`: one list for both
+ * would make every explanation a hop.
+ */
+ excluded: ExcludedCandidate[];
/** Mapped connections skipped because their route resolves to no claudish provider. */
unmappedRoutes: string[];
/** True when no catalog entry matched the name at all. */
@@ -199,21 +223,12 @@ function findCatalogEntry(entries: SlimModelEntry[], model: string): SlimModelEn
function gatherFromConnections(
entry: SlimModelEntry,
candidates: RouteCandidate[],
+ excluded: ExcludedCandidate[],
unmappedRoutes: Set<string>
): void {
for (const connection of entry.aggregators ?? []) {
if (connection.routeStatus !== "mapped") continue;
-
- // EVERY provider bound to this route, not just the first. One endpoint can
- // wear several claudish names, each owning a different key silo, and the
- // user's credential may be in any of them — see `routingProvidersForRoute`.
- // The routing table only: a lookup-only name is never a candidate.
- const bound = routingProvidersForRoute(connection.route);
- const routable = bound.filter((name) => getProviderByName(name)?.tier !== undefined);
- if (routable.length === 0) {
- unmappedRoutes.add(routeLabel(connection.route));
- continue;
- }
+ const routable = routableProviders(connection, unmappedRoutes);
for (const provider of routable) {
const tier = getProviderByName(provider)?.tier;
@@ -222,25 +237,91 @@ function gatherFromConnections(
const wireId = externalIdFor(entry, provider);
if (!wireId || wireId !== connection.externalModelId) continue;
- candidates.push({
- provider,
- wireId,
- tier,
- isVendorOwn: isVendorOwnRoute(connection.route, entry),
- price: connectionPrice(connection.pricing),
- // A connection that omits `contextWindow` serves the model's headline
- // window — that is what the field's absence MEANS in the contract, not
- // missing data. Carrying the entry's value is therefore reading the
- // catalog, not defaulting: without it, `openai-codex`'s measured 372K cap
- // on gpt-5.6-sol would sort AHEAD of the OpenAI API's full 1.05M, which
- // publishes no per-connection number because it is the headline one.
- contextWindow: connection.contextWindow ?? entry.contextWindow,
- source: "catalog-connection",
+ candidates.push(connectionCandidate(entry, connection, provider, tier, wireId));
+ }
+ }
+
+ // Content-use opt-in rows (`content-use.ts`). They were moved out of
+ // `aggregators` where the catalog entered memory, so nothing above can pick
+ // one. They are EXPLAINED here, never returned as candidates: a provider that
+ // maps this model ONLY through an opt-in id (OpenCode Go's
+ // `muse-spark-1.3-contributor`) shows in `--probe` as dropped, with the reason.
+ // A provider that also maps a plain id already has its candidate, and its
+ // opt-in sibling is not news.
+ const gatheredProviders = new Set(candidates.map((candidate) => candidate.provider));
+ for (const connection of entry.optInConnections ?? []) {
+ if (connection.routeStatus !== "mapped") continue;
+ for (const provider of routableProviders(connection, unmappedRoutes)) {
+ const tier = getProviderByName(provider)?.tier;
+ if (!tier || gatheredProviders.has(provider)) continue;
+
+ const wireId = optInIdFor(entry, provider);
+ if (!wireId || wireId !== connection.externalModelId) continue;
+
+ excluded.push({
+ candidate: connectionCandidate(entry, connection, provider, tier, wireId),
+ outcome: "excluded-by-content-use",
});
}
}
}
+/**
+ * EVERY provider bound to a connection's route, not just the first. One endpoint
+ * can wear several claudish names, each owning a different key silo, and the
+ * user's credential may be in any of them — see `routingProvidersForRoute`. The
+ * routing table only: a lookup-only name is never a candidate. A route bound to
+ * no defined provider is counted in `unmappedRoutes`.
+ */
+function routableProviders(connection: AggregatorEntry, unmappedRoutes: Set<string>): string[] {
+ const bound = routingProvidersForRoute(connection.route);
+ const routable = bound.filter((name) => getProviderByName(name)?.tier !== undefined);
+ if (routable.length === 0) unmappedRoutes.add(routeLabel(connection.route));
+ return routable;
+}
+
+/**
+ * The opt-in wire id `provider` publishes for the entry, chosen like
+ * {@link externalIdFor} (an exact id over a moving pointer). Only to EXPLAIN a
+ * drop; nothing sends it.
+ */
+function optInIdFor(entry: SlimModelEntry, provider: string): string | null {
+ const wireIds = (entry.optInConnections ?? []).flatMap((connection) =>
+ connection.routeStatus === "mapped" &&
+ catalogRouteMatchesProvider(connection.route, provider) &&
+ typeof connection.externalModelId === "string"
+ ? [connection.externalModelId]
+ : []
+ );
+ if (wireIds.length === 0) return null;
+ if (isMovingPointer(entry.modelId)) return wireIds[0] ?? null;
+ return wireIds.find((wireId) => !isMovingPointer(wireId)) ?? null;
+}
+
+function connectionCandidate(
+ entry: SlimModelEntry,
+ connection: AggregatorEntry,
+ provider: string,
+ tier: RouteTier,
+ wireId: string
+): RouteCandidate {
+ return {
+ provider,
+ wireId,
+ tier,
+ isVendorOwn: isVendorOwnRoute(connection.route, entry),
+ price: connectionPrice(connection.pricing),
+ // A connection that omits `contextWindow` serves the model's headline
+ // window — that is what the field's absence MEANS in the contract, not
+ // missing data. Carrying the entry's value is therefore reading the
+ // catalog, not defaulting: without it, `openai-codex`'s measured 372K cap
+ // on gpt-5.6-sol would sort AHEAD of the OpenAI API's full 1.05M, which
+ // publishes no per-connection number because it is the headline one.
+ contextWindow: connection.contextWindow ?? entry.contextWindow,
+ source: "catalog-connection",
+ };
+}
+
/**
* The vendor that MAKES the model is the vendor whose own route this is.
*
@@ -408,29 +489,41 @@ export function gatherRouteCandidates(model: string, cachePath?: string): Candid
const entry = entries ? findCatalogEntry(entries, model) : undefined;
const gathered: RouteCandidate[] = [];
+ const setAside: ExcludedCandidate[] = [];
const unmappedRoutes = new Set<string>();
// Source order is the dedupe rule: a real catalog connection beats a namespace
// claim for the same (provider, wireId), because it carries a price and a
// window the claim cannot know.
- if (entry) gatherFromConnections(entry, gathered, unmappedRoutes);
+ if (entry) gatherFromConnections(entry, gathered, setAside, unmappedRoutes);
gatherFromNamespaceClaims(model, entry, gathered);
+ // JSON, not a delimiter: an injective key is the whole requirement, and any
+ // literal separator is a guess about what a wire id cannot contain. This line
+ // briefly held a raw NUL byte, which made `file(1)` report the module as
+ // binary and grep stop matching it — the trap `devin.ts` hit once before.
+ const keyOf = (candidate: RouteCandidate) =>
+ JSON.stringify([candidate.provider, candidate.wireId]);
const seen = new Set<string>();
const candidates = gathered.filter((candidate) => {
- // JSON, not a delimiter: an injective key is the whole requirement, and any
- // literal separator is a guess about what a wire id cannot contain. This line
- // briefly held a raw NUL byte, which made `file(1)` report the module as
- // binary and grep stop matching it — the trap `devin.ts` hit once before.
- const key = JSON.stringify([candidate.provider, candidate.wireId]);
+ const key = keyOf(candidate);
if (seen.has(key)) return false;
seen.add(key);
return true;
});
candidates.sort(compareRouteCandidates);
+ const excluded = setAside.filter(({ candidate }) => {
+ const key = keyOf(candidate);
+ if (seen.has(key)) return false;
+ seen.add(key);
+ return true;
+ });
+ excluded.sort((a, b) => compareRouteCandidates(a.candidate, b.candidate));
+
return {
candidates,
+ excluded,
unmappedRoutes: [...unmappedRoutes],
catalogMiss: entry === undefined,
catalogReadable: entries !== null && entries !== undefined,
@@ -488,12 +581,36 @@ export function catalogDeniesProvider(
// denied on every model `z-ai` serves, a denial built out of a second key
// silo. Comparing BINDINGS is what `externalIdFor` and `model-availability.ts`
// already do, for this reason.
+ //
+ // `aggregators` only, so a model this provider maps ONLY through a content-use
+ // opt-in id is denied implicitly: the fallback hop would otherwise send the
+ // plain name to a route that never published it (`content-use.ts`).
return !(entry.aggregators ?? []).some(
(connection) =>
connection.routeStatus === "mapped" && catalogRouteMatchesProvider(connection.route, provider)
);
}
+/**
+ * Does `provider` map `model` ONLY through a content-use opt-in wire id?
+ *
+ * True when the catalog entry has no ordinary mapped connection for the
+ * provider and at least one opt-in one (`content-use.ts`). For a routing entry
+ * that names a provider without a model (a user rule `["zgo"]`, the fallback
+ * hop): such a provider can only be sent the opt-in id, which claudish never
+ * chooses, or the plain name, which the route never published. False with no
+ * catalog or no entry — absence of evidence excludes nothing.
+ */
+export function catalogMapsOnlyOptIn(provider: string, model: string, cachePath?: string): boolean {
+ const entries = cachePath ? readAllModelsCache(cachePath)?.entries : getCatalogEntries();
+ if (!entries) return false;
+ const entry = findCatalogEntry(entries, model);
+ if (!entry) return false;
+ const mapsHere = (connection: AggregatorEntry) =>
+ connection.routeStatus === "mapped" && catalogRouteMatchesProvider(connection.route, provider);
+ return !(entry.aggregators ?? []).some(mapsHere) && (entry.optInConnections ?? []).some(mapsHere);
+}
+
/** Who decides which models a route serves. `unknown` denies nothing. */
export type RouteOwnership = "backend-owned" | "account-selected" | "unknown";
diff --git a/packages/cli/src/providers/routing-rules.ts b/packages/cli/src/providers/routing-rules.ts
index a2257645..133eb195 100644
--- a/packages/cli/src/providers/routing-rules.ts
+++ b/packages/cli/src/providers/routing-rules.ts
@@ -20,6 +20,8 @@ import { type RouteTier, getProviderByName } from "./provider-definitions.js";
import {
type RouteCandidate,
catalogDeniesProvider,
+ catalogMapsOnlyOptIn,
+ compareRouteCandidates,
gatherRouteCandidates,
} from "./route-candidates.js";
import { buildCredentialHint } from "./routing-hints.js";
@@ -284,7 +286,7 @@ export function buildRoutingChain(
cachePath?: string
): Route[] {
return resolveRoutingEntries(entries, originalModelName, cachePath)
- .filter((resolved) => !resolved.excludedByMembership)
+ .filter((resolved) => !resolved.exclusion)
.map((resolved) => resolved.route);
}
@@ -292,11 +294,23 @@ export function buildRoutingChain(
interface ResolvedEntry {
route: Route;
/**
- * The entry's subscription plan publishes a membership that does not include
- * the model. `route` then carries the name it would have been asked by, since
- * no wire id was resolved for it.
+ * Set when the entry is excluded before any credential is read. `route` then
+ * carries the name it would have been asked by, since no wire id was resolved.
+ *
+ * - `excluded-by-membership`: the entry's subscription plan publishes a
+ * membership that does not include the model.
+ * - `excluded-by-content-use`: the provider maps the model only through a
+ * content-use opt-in wire id, which claudish never chooses (`content-use.ts`).
*/
- excludedByMembership: boolean;
+ exclusion?: PreFilterExclusion;
+}
+
+/** The outcomes that remove a candidate before the credential filter runs. */
+type PreFilterExclusion = "excluded-by-membership" | "excluded-by-content-use";
+
+/** Whether a candidate was removed before the credential filter, i.e. never reaches it. */
+function isPreFilterExclusion(outcome: CandidateOutcome): boolean {
+ return outcome === "excluded-by-membership" || outcome === "excluded-by-content-use";
}
/**
@@ -338,7 +352,21 @@ function resolveRoutingEntries(
if (atIdx === -1) {
const routing = resolveSubscriptionRouting(modelName, provider, cachePath);
if (routing.kind === "not-served") {
- resolved.push({ route: routeFor(provider, modelName), excludedByMembership: true });
+ resolved.push({
+ route: routeFor(provider, modelName),
+ exclusion: "excluded-by-membership",
+ });
+ continue;
+ }
+ // The provider publishes this model ONLY through a content-use opt-in
+ // wire id. Sending the plain name would ask a route for an id it never
+ // published, and sending the opt-in id would choose it for the user
+ // (`content-use.ts`). A `["zgo"]` rule for `gemini-4-argon` lands here.
+ if (routing.kind !== "serves" && catalogMapsOnlyOptIn(provider, modelName, cachePath)) {
+ resolved.push({
+ route: routeFor(provider, modelName),
+ exclusion: "excluded-by-content-use",
+ });
continue;
}
if (routing.kind === "serves") {
@@ -358,7 +386,7 @@ function resolveRoutingEntries(
modelName = resolveExternalId(modelName, provider, cachePath) ?? modelName;
}
- resolved.push({ route: routeFor(provider, modelName), excludedByMembership: false });
+ resolved.push({ route: routeFor(provider, modelName) });
}
return resolved;
@@ -469,7 +497,12 @@ export type CandidateOutcome =
/** The account's dynamic models catalog denies the model. */
| "not-served"
/** The subscription plan's published membership does not include the model. */
- | "excluded-by-membership";
+ | "excluded-by-membership"
+ /**
+ * The provider maps the model only through a content-use opt-in wire id, which
+ * claudish never chooses; typed exactly (`provider@<id>`), it is sent.
+ */
+ | "excluded-by-content-use";
/** One route candidate, where the chain placed it, and what became of it. */
export interface ExplainedCandidate {
@@ -638,7 +671,7 @@ function explainCandidate(
/** The outcome of a resolved routing entry before any credential is read. */
function entryOutcome(resolved: ResolvedEntry): CandidateOutcome {
- return resolved.excludedByMembership ? "excluded-by-membership" : "kept";
+ return resolved.exclusion ?? "kept";
}
/**
@@ -680,7 +713,7 @@ async function explainExplicitSpec(
return explanation;
}
- if (resolved.excludedByMembership) {
+ if (resolved.exclusion) {
explanation.outcome = {
kind: "no-route",
cause: "explicit-unbuildable",
@@ -790,7 +823,7 @@ export function buildCatalogChain(
const chain = explainCatalogChain(model, defaultProvider, cachePath);
return {
routes: chain.candidates
- .filter((candidate) => candidate.outcome !== "excluded-by-membership")
+ .filter((candidate) => !isPreFilterExclusion(candidate.outcome))
.map(routeOf),
catalogReadable: chain.catalog !== "unreadable",
};
@@ -823,8 +856,15 @@ function explainCatalogChain(
ensureEndpointsRegistered();
const gathering = gatherRouteCandidates(model, cachePath);
- const candidates = gathering.candidates.map((candidate) =>
- explainCandidate(routeFor(candidate.provider, candidate.wireId), "candidate", "kept", candidate)
+ // The gatherer's excluded candidates join the explanation with THEIR outcome,
+ // never `kept`, at the position the chain order gives them. They are shown by
+ // `--probe` and never become a hop: every filter below skips them.
+ const ordered: Array<{ gathered: RouteCandidate; outcome: CandidateOutcome }> = [
+ ...gathering.candidates.map((gathered) => ({ gathered, outcome: "kept" as const })),
+ ...gathering.excluded.map(({ candidate, outcome }) => ({ gathered: candidate, outcome })),
+ ].sort((a, b) => compareRouteCandidates(a.gathered, b.gathered));
+ const candidates = ordered.map(({ gathered, outcome }) =>
+ explainCandidate(routeFor(gathered.provider, gathered.wireId), "candidate", outcome, gathered)
);
const catalog = !gathering.catalogReadable
? "unreadable"
@@ -841,7 +881,11 @@ function explainCatalogChain(
// published is a metered request billed for its own 404, and a name the
// backend has since RENAMED looks identical.
fallbackWithheld = "catalog-unreadable";
- } else if (candidates.some((candidate) => candidate.provider === fallback)) {
+ } else if (
+ candidates.some((candidate) => candidate.provider === fallback && candidate.outcome === "kept")
+ ) {
+ // A KEPT candidate only: an excluded one is not in the chain, so the fallback
+ // still gets its own say (and the catalog's denial, or its own exclusion).
fallbackWithheld = "already-gathered";
} else if (catalogDeniesProvider(fallback, model, cachePath)) {
fallbackWithheld = "catalog-denies";
@@ -997,7 +1041,7 @@ async function explainBareName(
}
const remaining = explanation.candidates.filter(
- (candidate) => candidate.outcome !== "excluded-by-membership"
+ (candidate) => !isPreFilterExclusion(candidate.outcome)
);
// NO CATALOG MEANS LOCAL ONLY. With nothing readable, claudish knows no
@@ -1590,6 +1634,7 @@ const DROPPED_FALLBACK_PHRASE: Record<Exclude<CandidateOutcome, "kept">, string>
"credential-unreadable": "has a credential that could not be read",
"not-served": "does not serve it",
"excluded-by-membership": "is outside its plan's membership",
+ "excluded-by-content-use": "maps it only through a contributor (content-use opt-in) id",
};
/**
diff --git a/packages/cli/src/providers/transport/probe-discovery.ts b/packages/cli/src/providers/transport/probe-discovery.ts
index c6c9126f..da322e57 100644
--- a/packages/cli/src/providers/transport/probe-discovery.ts
+++ b/packages/cli/src/providers/transport/probe-discovery.ts
@@ -14,6 +14,7 @@
import { log } from "../../logger.js";
import { readAllModelsCache } from "../all-models-cache.js";
+import { isOptInWireId } from "../content-use.js";
/**
* In-memory cache. Stores the FULL ranked list of candidates so the probe
@@ -453,8 +454,12 @@ export function rankProbeCandidates(names: string[]): string[] {
// containing `*` is a LiteLLM ROUTE PATTERN (`gemini/*`), not a model id, so
// there is nothing to send it. Dropping it is rejecting a non-identifier, not
// guessing what it can do — which is why it stays after the name rules went.
+ //
+ // The other is not a capability judgement either: a content-use opt-in wire
+ // id is never a probe pick, because a probe is a request claudish chose to
+ // send (`content-use.ts`). Every endpoint probe pick is ranked here.
return names
- .filter((name) => !name.includes("*"))
+ .filter((name) => !name.includes("*") && !isOptInWireId(name))
.sort((a, b) => {
const aStd = isStandardName(a);
const bStd = isStandardName(b);
@@ -719,7 +724,9 @@ interface OllamaModel {
* the fall-through list the probe loop depends on.
*/
function orderByCost(models: OllamaModel[]): string[] {
- const sized = models.filter((m) => typeof m.size === "number");
+ // The opt-in exclusion `rankProbeCandidates` applies, for the sized half that
+ // does not pass through it.
+ const sized = models.filter((m) => typeof m.size === "number" && !isOptInWireId(m.name));
const unsized = models.filter((m) => typeof m.size !== "number");
const bySize = [...sized]
.sort((a, b) => (a.size ?? Number.POSITIVE_INFINITY) - (b.size ?? Number.POSITIVE_INFINITY))
diff --git a/packages/cli/src/tui/components/RoutingContent.tsx b/packages/cli/src/tui/components/RoutingContent.tsx
index ca8e367d..802028c5 100644
--- a/packages/cli/src/tui/components/RoutingContent.tsx
+++ b/packages/cli/src/tui/components/RoutingContent.tsx
@@ -30,6 +30,7 @@ const DROPPED_TEXT: Record<DroppedOutcome, string> = {
"credential-unreadable": "credential could not be read",
"not-served": "the account does not serve it",
"excluded-by-membership": "not in the plan's membership",
+ "excluded-by-content-use": "contributor id: content-use opt-in, type it exactly to use it",
};
/**