Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* The catalog's recommended reasoning effort per model and task type, kept in a
* sidecar next to the cloud models catalog cache
* (`cloud-models-catalog-v3.efforts.json`).
*
* Source: `data.recommendations.efforts` of `?catalog=recommended` (models-index
* 2.3.0), an OPTIONAL field: `{ [canonical model id]: { [task type]: { effort,
* basis, sendableOn, evidence, ... } } }`. Absent, malformed or not an object
* means no recommendations. Task types, basis values and cell fields are open
* sets: an unknown type or basis is kept, an unknown field ignored, never
* rejected. `sendableOn` lists the connections allowed to send the effort; a
* cell without one is skipped.
*
* Its own file for the reason the route registry has one
* (`routeRegistryPathFor`): the recommended-models cache is discarded for
* display reasons, and older claudish builds rewrite the main catalog file.
*
* Several generations are kept, newest first. A connection is pinned to the
* generation its handler was built on, handlers are cached for the process,
* and nothing rebuilds them on a generation change: a long session whose
* catalog another process refreshed (a team slot's start) still finds the
* efforts of its own generation, which its own startup warm wrote.
*
* Every proxy start warms, so writers run concurrently: each one reads, merges,
* writes a temp file in the same directory and renames it over the target, so a
* reader never sees a torn file. A lost update between two writers of different
* generations can drop one entry; the lookup then reports `generation`, never a
* wrong value.
*
* claudish never picks a task type itself. The MCP `list_models` tool shows this
* table, and the calling agent, which knows its task, passes one effort per model
* to `team`, `create_session` or `run_prompt` (ai-docs/architecture/wire.md
* "Recommended effort").
*/
import { readFileSync, statSync } from "node:fs";
import { writeFileAtomic } from "../fs-atomic.js";
import { log } from "../logger.js";
import { ALL_MODELS_CACHE_PATH } from "./all-models-cache.js";
/**
* One connection a recommendation may be sent on: its route binding, wire id,
* and how the effort is encoded there. Only `request_parameter` is sendable;
* `model_id_switch` is reserved by the backend for a later phase, and a missing
* or other value means "not sendable on this connection".
*/
export interface EffortSendableOn {
routeId: string;
routeProfileId: string;
externalModelId: string;
encoding?: string;
}
/** The one `encoding` claudish sends: the effort is a request parameter. */
export const SENDABLE_ENCODING = "request_parameter";
/**
* One recommendation: the catalog effort name, why (logged only), and the
* connections it may be sent on (never empty).
*/
export interface EffortRecommendation {
effort: string;
basis?: string;
sendableOn: readonly EffortSendableOn[];
}
/** A model's recommendations, keyed by task type. */
export type ModelEffortRecommendations = Readonly<Record<string, EffortRecommendation>>;
export interface CachedEffortRecommendations {
contractVersion: 3;
/** The sidecar's own layout ({@link SIDECAR_FORMAT}). */
format: 2;
generations: Readonly<
Record<
string,
{
writtenAt: number;
efforts: Readonly<Record<string, ModelEffortRecommendations>>;
}
>
>;
}
export type EffortLookup =
| { ok: true; byTaskType: ModelEffortRecommendations }
| { ok: false; reason: "no-sidecar" | "generation" | "model" | "declared"; detail: string };
const SIDECAR_CONTRACT_VERSION = 3;
/**
* The sidecar layout. 2 added `sendableOn` per cell (models-index 2.3.0). A file
* without it, written before, reads as no sidecar, never as cells with no
* connection, and the next warm replaces it whole.
*/
const SIDECAR_FORMAT = 2;
/** Generations kept in the sidecar; the oldest `writtenAt` beyond this is evicted. */
const MAX_GENERATIONS = 4;
/** Where the efforts sidecar for the cache at `catalogPath` is kept. */
export function effortRecommendationsPathFor(catalogPath: string): string {
return catalogPath.endsWith(".json")
? `${catalogPath.slice(0, -5)}.efforts.json`
: `${catalogPath}.efforts.json`;
}
/** `~/.claudish/cloud-models-catalog-v3.efforts.json`. */
export const EFFORT_RECOMMENDATIONS_PATH = effortRecommendationsPathFor(ALL_MODELS_CACHE_PATH);
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
/**
* Normalise the backend's `efforts` field. Never throws: anything that is not
* an object gives `{}`. Only `effort`, `basis` and `sendableOn` are kept
* (`evidence`, `proposed`, `flags`, `unverifiedOn` and any other field are
* dropped). A task entry without a non-empty string `effort`, or without one
* well-formed `sendableOn` element, is skipped, and a model left with no entry
* is skipped too, so a lookup reports it as absent. `basis` is kept verbatim
* when it is a string, whatever its value.
*/
export function parseEffortRecommendations(
raw: unknown
): Record<string, ModelEffortRecommendations> {
const out: Record<string, ModelEffortRecommendations> = {};
if (!isRecord(raw)) return out;
for (const [modelId, byTask] of Object.entries(raw)) {
const entries = modelId ? parseModelEntries(byTask) : {};
if (Object.keys(entries).length > 0) out[modelId] = entries;
}
return out;
}
/** One model's task entries; malformed ones are skipped. */
function parseModelEntries(byTask: unknown): Record<string, EffortRecommendation> {
const entries: Record<string, EffortRecommendation> = {};
if (!isRecord(byTask)) return entries;
for (const [taskType, entry] of Object.entries(byTask)) {
if (!taskType || !isRecord(entry)) continue;
if (typeof entry.effort !== "string" || entry.effort === "") continue;
const sendableOn = parseSendableOn(entry.sendableOn);
if (sendableOn.length === 0) continue;
entries[taskType] =
typeof entry.basis === "string"
? { effort: entry.effort, basis: entry.basis, sendableOn }
: { effort: entry.effort, sendableOn };
}
return entries;
}
function nonEmptyString(value: unknown): value is string {
return typeof value === "string" && value !== "";
}
/**
* A cell's `sendableOn`: the elements naming a route binding and a wire id as
* non-empty strings. `encoding` is kept when it is a string (any value; the
* decision reads it) and omitted otherwise. Other fields are dropped.
*/
function parseSendableOn(raw: unknown): EffortSendableOn[] {
if (!Array.isArray(raw)) return [];
const out: EffortSendableOn[] = [];
for (const item of raw) {
if (!isRecord(item)) continue;
const { routeId, routeProfileId, externalModelId, encoding } = item;
if (!nonEmptyString(routeId) || !nonEmptyString(routeProfileId)) continue;
if (!nonEmptyString(externalModelId)) continue;
out.push(
typeof encoding === "string"
? { routeId, routeProfileId, externalModelId, encoding }
: { routeId, routeProfileId, externalModelId }
);
}
return out;
}
/**
* The sidecar as stored, re-normalised; null when absent, not a sidecar, or of
* an older format (so it reads as "no recommendations", never as a wrong one).
*/
function parseSidecar(raw: unknown): CachedEffortRecommendations | null {
if (!isRecord(raw) || raw.contractVersion !== SIDECAR_CONTRACT_VERSION) return null;
if (raw.format !== SIDECAR_FORMAT) return null;
if (!isRecord(raw.generations)) return null;
const generations: Record<
string,
{ writtenAt: number; efforts: Record<string, ModelEffortRecommendations> }
> = {};
for (const [generationId, generation] of Object.entries(raw.generations)) {
if (!generationId || !isRecord(generation)) continue;
if (typeof generation.writtenAt !== "number" || !Number.isFinite(generation.writtenAt)) {
continue;
}
generations[generationId] = {
writtenAt: generation.writtenAt,
efforts: parseEffortRecommendations(generation.efforts),
};
}
return { contractVersion: SIDECAR_CONTRACT_VERSION, format: SIDECAR_FORMAT, generations };
}
function statOrNull(path: string): { mtimeMs: number; size: number } | null {
try {
const { mtimeMs, size } = statSync(path);
return { mtimeMs, size };
} catch {
return null;
}
}
function readSidecarFile(path: string): CachedEffortRecommendations | null {
try {
return parseSidecar(JSON.parse(readFileSync(path, "utf-8")));
} catch (err) {
// A corrupt file reads as none: list_models drops the effort table. Say why.
if ((err as NodeJS.ErrnoException)?.code !== "ENOENT") {
log(`[effort] unreadable ${path}: ${err instanceof Error ? err.message : String(err)}`);
}
return null;
}
}
/** The `format` of a sidecar file this build does not read, or undefined. */
function foreignSidecarFormat(path: string): unknown {
try {
const raw: unknown = JSON.parse(readFileSync(path, "utf-8"));
if (isRecord(raw) && raw.format !== SIDECAR_FORMAT) return raw.format ?? "none";
} catch {
// Absent or unreadable: nothing of another build's to replace.
}
return undefined;
}
// A sidecar of another format is replaced, and that is said once per process:
// two builds of different formats sharing ~/.claudish discard each other's
// generations on every write, and the log line is how that shows.
let _foreignFormatLogged = false;
// The request path looks recommendations up per request: parsed results are
// memoized per path, keyed by the file's mtime and size, so a rewrite (by this
// process or another) is seen on the next read.
const _readMemo = new Map<string, { key: string; sidecar: CachedEffortRecommendations | null }>();
export function _clearEffortRecommendationsMemo(): void {
_readMemo.clear();
_foreignFormatLogged = false;
}
/** The sidecar at `path`, or null when it is absent, unreadable or malformed. */
export function readEffortRecommendations(
path: string = EFFORT_RECOMMENDATIONS_PATH
): CachedEffortRecommendations | null {
const stat = statOrNull(path);
if (!stat) {
_readMemo.delete(path);
return null;
}
const key = `${stat.mtimeMs}:${stat.size}`;
const memo = _readMemo.get(path);
if (memo && memo.key === key) return memo.sidecar;
const sidecar = readSidecarFile(path);
_readMemo.set(path, { key, sidecar });
return sidecar;
}
/**
* Record generation `generationId`'s efforts (`raw` is the backend's
* `recommendations.efforts`, possibly absent). An absent or non-object field is
* written as `efforts: {}`, so the generation says "none" rather than missing.
* Replaces that generation's entry, keeps the newest {@link MAX_GENERATIONS} by
* `writtenAt`, and writes through a temp file renamed over the target. Throws on
* a write failure; the caller decides whether that matters.
*/
export function writeEffortRecommendations(
generationId: string,
raw: unknown,
path: string = EFFORT_RECOMMENDATIONS_PATH
): void {
const existing = readSidecarFile(path);
if (!existing && !_foreignFormatLogged) {
const foreign = foreignSidecarFormat(path);
if (foreign !== undefined) {
_foreignFormatLogged = true;
log(
`[effort] replacing a sidecar of format ${String(foreign)} with format ${SIDECAR_FORMAT} at ${path}; its generations are dropped`
);
}
}
const merged: CachedEffortRecommendations["generations"] = {
...(existing?.generations ?? {}),
[generationId]: { writtenAt: Date.now(), efforts: parseEffortRecommendations(raw) },
};
const kept = Object.entries(merged)
.sort(([, a], [, b]) => b.writtenAt - a.writtenAt)
.slice(0, MAX_GENERATIONS);
const sidecar: CachedEffortRecommendations = {
contractVersion: SIDECAR_CONTRACT_VERSION,
format: SIDECAR_FORMAT,
generations: Object.fromEntries(kept),
};
writeFileAtomic(path, JSON.stringify(sidecar));
_readMemo.delete(path);
}
/**
* The recommendations for `modelId` (the connection's canonical model id,
* exactly: never a base model, family or sibling) at the connection's
* generation. A miss names why: `declared` (a custom endpoint or off-catalog
* fallback has no catalog generation), `no-sidecar`, `generation` (the sidecar
* does not hold the connection's generation) or `model` (no entry for it).
*/
export function lookupModelEfforts(
modelId: string,
generationId: string,
path: string = EFFORT_RECOMMENDATIONS_PATH
): EffortLookup {
if (generationId === "declared") {
return { ok: false, reason: "declared", detail: "declared wire: no catalog generation" };
}
const sidecar = readEffortRecommendations(path);
if (!sidecar) {
return {
ok: false,
reason: "no-sidecar",
detail: `no efforts sidecar (or one of an older format) at ${path}`,
};
}
const generation = sidecar.generations[generationId];
if (!generation) {
const held = Object.keys(sidecar.generations);
return {
ok: false,
reason: "generation",
detail: `efforts sidecar holds ${held.length > 0 ? held.join(", ") : "no generation"}, not ${generationId}`,
};
}
const byTaskType = generation.efforts[modelId];
if (!byTaskType) {
return {
ok: false,
reason: "model",
detail: `no recommended efforts for ${modelId} in ${generationId}`,
};
}
return { ok: true, byTaskType };
}
/**
* The newest generation the sidecar holds (by `writtenAt`), or null when there is
* no sidecar or it holds none. For display: `list_models` shows the table the
* last catalog refresh wrote.
*/
export function latestEffortRecommendations(path: string = EFFORT_RECOMMENDATIONS_PATH): {
generationId: string;
efforts: Readonly<Record<string, ModelEffortRecommendations>>;
} | null {
const sidecar = readEffortRecommendations(path);
if (!sidecar) return null;
const newest = Object.entries(sidecar.generations).sort(
([, a], [, b]) => b.writtenAt - a.writtenAt
)[0];
return newest ? { generationId: newest[0], efforts: newest[1].efforts } : null;
}