@buyong/pi-devin 0.0.0-stage → 0.1.1

package/src/core/inference/chat.ts

@@ -0,0 +1,229 @@
+import { randomUUID } from "node:crypto";
+import { object, requiredString, tokenCount, type ChatMessage, type ChatResult, type ChatTool, type ImageData, type JsonObject, type ToolCall, type Usage } from "../types.ts";
+import type { ConnectClient } from "../protocol/transport.ts";
+import { CHAT_METHOD } from "../protocol/protobuf.ts";
+import { wireMessages } from "./messages.ts";
+
+export const DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant. Follow the user\'s request concisely.";
+
+export function userMessage(prompt: string, images: readonly ImageData[] = []): ChatMessage {
+  return {
+    messageId: randomUUID(), source: "CHAT_MESSAGE_SOURCE_USER", prompt,
+    ...(images.length ? { images: images.map((image) => ({ ...image })) } : {}),
+  };
+}
+
+export function chatRequest(options: {
+  metadata: JsonObject;
+  model: string;
+  messages: ChatMessage[];
+  systemPrompt: string;
+  maxTokens: number;
+  cascadeId: string;
+  trajectoryId: string;
+  executionId?: string;
+  clientSessionId?: string;
+  modelAssignmentJwt?: string;
+  stepIndex?: number;
+  isAuxiliary?: boolean;
+  isRecovery?: boolean;
+  includeContext?: boolean;
+  cwd?: string;
+  tools?: ChatTool[];
+}): JsonObject {
+  return {
+    metadata: options.metadata,
+    prompt: options.systemPrompt,
+    chatMessagePrompts: wireMessages(options.messages, { includeContext: options.includeContext, cwd: options.cwd }),
+    chatModelUid: options.model,
+    requestType: "CHAT_MESSAGE_REQUEST_TYPE_CASCADE",
+    configuration: {
+      maxTokens: options.maxTokens,
+      numCompletions: 1,
+      maxNewlines: 400,
+      temperature: 1,
+      topK: 40,
+      topP: Math.fround(0.95),
+    },
+    trajectoryReference: {
+      trajectoryId: options.trajectoryId,
+      trajectoryType: "CORTEX_TRAJECTORY_TYPE_CASCADE",
+      ...(!options.isAuxiliary && !options.isRecovery && options.messages.at(-1)?.source === "CHAT_MESSAGE_SOURCE_USER" ? { stepType: "CORTEX_STEP_TYPE_USER_INPUT" } : {}),
+      ...(options.stepIndex ? { stepIndex: options.stepIndex } : {}),
+    },
+    cascadeId: options.cascadeId,
+    plannerMode: "CONVERSATIONAL_PLANNER_MODE_DEFAULT",
+    ...(!options.isAuxiliary && options.executionId ? { executionId: options.executionId } : {}),
+    ...(options.clientSessionId ? { clientSessionId: options.clientSessionId } : {}),
+    ...(options.modelAssignmentJwt ? { modelAssignmentJwt: options.modelAssignmentJwt } : {}),
+    ...(options.tools?.length ? { tools: options.tools } : {}),
+  };
+}
+
+/** Attaches argument deltas without an ID to the call that started with the first ID. Ambiguous parallel deltas are rejected. */
+export class ChatAccumulator {
+  readonly message: ChatMessage = { messageId: "", source: "CHAT_MESSAGE_SOURCE_SYSTEM", prompt: "" };
+  readonly usage: Usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 };
+  readonly calls = new Map<string, ToolCall>();
+  private currentCall?: ToolCall;
+  private hasEnded = false;
+  private startedAt = performance.now();
+  private firstDeltaMs?: number;
+  private stopReason = "";
+  private usageReported = false;
+  private frameCount = 0;
+  private stopFrameIndex?: number;
+  private lastUsageFrameIndex?: number;
+  private idlessToolDeltaCount = 0;
+  private actualModelUid?: string;
+  private usageModelUid?: string;
+
+  accept(data: JsonObject, isEnd = false): void {
+    if (this.hasEnded) throw new Error("Cannot accumulate a response after EndStream.");
+    this.frameCount++;
+    if (isEnd) {
+      if (data.error) throw new Error("An error EndStream cannot be treated as success.");
+      this.hasEnded = true;
+      return;
+    }
+    if (data.redact === true) throw new Error("The server redacted the response.");
+    if (typeof data.messageId === "string" && data.messageId) this.message.messageId = data.messageId;
+    if (data.thinkingRedacted === true) {
+      this.message.thinkingRedacted = true;
+      this.message.thinking = "";
+    }
+    if (typeof data.deltaText === "string") this.message.prompt += data.deltaText;
+    if (typeof data.deltaThinking === "string" && !this.message.thinkingRedacted) {
+      this.message.thinking = (this.message.thinking ?? "") + data.deltaThinking;
+    }
+    if (typeof data.deltaSignature === "string") this.message.signature = (this.message.signature ?? "") + data.deltaSignature;
+    for (const [source, target] of [
+      ["deltaSignatureType", "signatureType"], ["geminiThoughtSignature", "geminiThoughtSignature"],
+      ["outputId", "outputId"], ["thinkingId", "thinkingId"], ["phase", "phase"],
+    ] as const) {
+      if (typeof data[source] === "string") this.message[target] = data[source];
+    }
+    if (typeof data.actualModelUid === "string") this.actualModelUid = data.actualModelUid;
+    if (data.deltaToolCalls !== undefined) {
+      if (!Array.isArray(data.deltaToolCalls)) throw new Error("deltaToolCalls must be an array.");
+      for (const value of data.deltaToolCalls) {
+        const delta = object(value, "tool delta");
+        const id = typeof delta.id === "string" && delta.id ? delta.id : undefined;
+        if (id) {
+          let call = this.calls.get(id);
+          if (!call) {
+            call = { id, name: "", argumentsJson: "" };
+            this.calls.set(id, call);
+          }
+          this.currentCall = call;
+        } else {
+          this.idlessToolDeltaCount++;
+          if (data.deltaToolCalls.length !== 1 || !this.currentCall || this.calls.size > 1) {
+            throw new Error("Cannot attach a delta without a tool ID to a specific call.");
+          }
+        }
+        const call = this.currentCall!;
+        if (delta.isCustomToolCall) throw new Error("Grammar-based custom tools are not supported.");
+        if (delta.invalidJsonErr || delta.invalidJsonStr) throw new Error("The server reported a tool argument JSON error.");
+        if (typeof delta.name === "string") call.name += delta.name;
+        if (typeof delta.argumentsJson === "string") call.argumentsJson += delta.argumentsJson;
+      }
+    }
+    if (data.deltaText || data.deltaThinking || data.deltaToolCalls) {
+      this.firstDeltaMs ??= performance.now() - this.startedAt;
+    }
+    if (typeof data.stopReason === "string" && data.stopReason) {
+      this.stopReason = data.stopReason;
+      this.stopFrameIndex = this.frameCount;
+    }
+    if (data.usage !== undefined) {
+      const usage = object(data.usage, "usage");
+      if (typeof usage.modelUid === "string") this.usageModelUid = usage.modelUid;
+      for (const [source, target] of [
+        ["inputTokens", "input"], ["outputTokens", "output"],
+        ["cacheReadTokens", "cacheRead"], ["cacheWriteTokens", "cacheWrite"],
+      ] as const) {
+        if (usage[source] !== undefined) {
+          this.usage[target] = tokenCount(usage[source], source);
+          this.usageReported = true;
+          this.lastUsageFrameIndex = this.frameCount;
+        }
+      }
+      this.usage.totalTokens = this.usage.input + this.usage.output + this.usage.cacheRead + this.usage.cacheWrite;
+    }
+  }
+
+  finish(): ChatResult {
+    if (!this.hasEnded) throw new Error("No successful EndStream.");
+    if (!["STOP_REASON_STOP_PATTERN", "STOP_REASON_FUNCTION_CALL", "STOP_REASON_MAX_TOKENS"].includes(this.stopReason)) {
+      throw new Error(`stopReason cannot be treated as success: ${this.stopReason || "(none)"}`);
+    }
+    if (this.calls.size > 0) {
+      this.message.toolCalls = [...this.calls.values()];
+      for (const call of this.message.toolCalls) {
+        requiredString(call.name, "tool name");
+        let args: unknown;
+        try { args = JSON.parse(call.argumentsJson); }
+        catch { throw new Error(`Arguments of tool ${call.name} are not valid JSON.`); }
+        object(args, "tool arguments");
+      }
+    }
+    if (this.stopReason === "STOP_REASON_FUNCTION_CALL" && !this.calls.size) {
+      throw new Error("The response ended with FUNCTION_CALL but has no tool call.");
+    }
+    if (this.calls.size && this.stopReason !== "STOP_REASON_FUNCTION_CALL") {
+      throw new Error("Tool calls and the stop reason do not match.");
+    }
+    this.message.messageId ||= randomUUID();
+    return {
+      message: this.message,
+      stopReason: this.stopReason,
+      usage: this.usage,
+      usageReported: this.usageReported,
+      frameCount: this.frameCount,
+      stopFrameIndex: this.stopFrameIndex,
+      lastUsageFrameIndex: this.lastUsageFrameIndex,
+      idlessToolDeltaCount: this.idlessToolDeltaCount,
+      durationMs: Math.round(performance.now() - this.startedAt),
+      firstDeltaMs: this.firstDeltaMs === undefined ? undefined : Math.round(this.firstDeltaMs),
+      actualModelUid: this.actualModelUid,
+      ...(this.usageModelUid ? { usageModelUid: this.usageModelUid } : {}),
+    };
+  }
+}
+
+export async function streamChat(
+  client: ConnectClient,
+  request: JsonObject,
+  options: { signal?: AbortSignal; onText?: (delta: string) => void; stage?: string; onDispatched?: () => void } = {},
+): Promise<ChatResult> {
+  const accumulator = new ChatAccumulator();
+  for await (const frame of client.stream(CHAT_METHOD, request, options.signal, { stage: options.stage, onDispatched: options.onDispatched })) {
+    accumulator.accept(frame.data, frame.isEnd);
+    if (!frame.isEnd && typeof frame.data.deltaText === "string") options.onText?.(frame.data.deltaText);
+  }
+  const result = accumulator.finish();
+  // Field 22 records the model of the generation request, not actualModelUid/usage.modelUid.
+  if (typeof request.chatModelUid === "string") result.message.modelUid = request.chatModelUid;
+  return result;
+}
+
+/** Raw thinking and signatures never go to logs or reports. They are only resent inside requests. */
+export function summarizeChat(result: ChatResult): JsonObject {
+  return {
+    text: result.message.prompt,
+    stopReason: result.stopReason,
+    usage: result.usage,
+    usageReported: result.usageReported,
+    toolCalls: result.message.toolCalls ?? [],
+    thinkingChars: result.message.thinking?.length ?? 0,
+    hasSignature: Boolean(result.message.signature || result.message.geminiThoughtSignature),
+    frameCount: result.frameCount,
+    stopFrameIndex: result.stopFrameIndex,
+    lastUsageFrameIndex: result.lastUsageFrameIndex,
+    idlessToolDeltaCount: result.idlessToolDeltaCount,
+    durationMs: result.durationMs,
+    firstDeltaMs: result.firstDeltaMs,
+    actualModelUid: result.actualModelUid,
+  };
+}

package/src/core/inference/images.ts

@@ -0,0 +1,24 @@
+import type { ImageData } from "../types.ts";
+
+export const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+export const MAX_IMAGES_BYTES = 5 * 1024 * 1024;
+
+export function imageMimeType(bytes: Uint8Array): ImageData["mimeType"] {
+  const data = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (data.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex"))) return "image/png";
+  if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return "image/jpeg";
+  if (["GIF87a", "GIF89a"].includes(data.subarray(0, 6).toString("ascii"))) return "image/gif";
+  if (data.length >= 12 && data.subarray(0, 4).toString("ascii") === "RIFF" && data.subarray(8, 12).toString("ascii") === "WEBP") return "image/webp";
+  throw new Error("Unsupported image. Use a PNG, JPEG, GIF or WebP file.");
+}
+
+export function imageFromBase64(data: string, mimeType: string): { image: ImageData; sizeBytes: number } {
+  if (data.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4 || data.length % 4 === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(data)) {
+    throw new Error("Invalid image Base64 format or size.");
+  }
+  const bytes = Buffer.from(data, "base64");
+  if (bytes.length > MAX_IMAGE_BYTES || bytes.toString("base64").replace(/=+$/, "") !== data.replace(/=+$/, "")) throw new Error("Invalid image Base64 format or size.");
+  const actualMimeType = imageMimeType(bytes);
+  if (mimeType !== actualMimeType) throw new Error("The image MIME type does not match its actual format.");
+  return { image: { base64Data: data, mimeType: actualMimeType }, sizeBytes: bytes.length };
+}

package/src/core/inference/messages.ts

@@ -0,0 +1,34 @@
+import { randomUUID } from "node:crypto";
+import { platform, release, type as osType } from "node:os";
+import type { ChatMessage, JsonObject } from "../types.ts";
+
+export function environmentContext(cwd: string, now = new Date()): string {
+  const platformName = platform() === "darwin" ? "macos" : platform() === "win32" ? "windows" : platform();
+  const date = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
+  const weekday = new Intl.DateTimeFormat("en-US", { weekday: "long" }).format(now);
+  return `<system_info>\nThe following information is automatically generated context about your current environment.\nCurrent workspace directories:\n  ${cwd} (cwd)\n\nPlatform: ${platformName}\nOS Version: ${osType()} ${release()}\nToday's date: ${weekday}, ${date}\n</system_info>`;
+}
+
+/** Creates new wire message IDs without mutating history objects. Tool call IDs, signatures and images are preserved. */
+export function wireMessages(messages: readonly ChatMessage[], options: { cwd?: string; includeContext?: boolean } = {}): JsonObject[] {
+  const wire = messages.map((message) => {
+    const result: JsonObject = { ...message, messageId: randomUUID() };
+    if (!message.prompt) delete result.prompt;
+    if (message.toolResultIsError === false) delete result.toolResultIsError;
+    if (message.thinking === "") delete result.thinking;
+    if (message.signature === "") delete result.signature;
+    if (message.source === "CHAT_MESSAGE_SOURCE_USER" || message.source === "CHAT_MESSAGE_SOURCE_TOOL") {
+      result.promptCacheOptions ??= { type: "CACHE_CONTROL_TYPE_EPHEMERAL" };
+    }
+    return result;
+  });
+  if (options.includeContext && wire.length) {
+    wire.unshift({ messageId: randomUUID(), source: "CHAT_MESSAGE_SOURCE_USER", prompt: environmentContext(options.cwd ?? process.cwd()) });
+    // Does not advertise built-in skills that do not exist here. The content is limited to allowed prompt/tool differences.
+    wire.splice(2, 0, {
+      messageId: randomUUID(), source: "CHAT_MESSAGE_SOURCE_USER",
+      prompt: "<available_skills>\nNo skills are configured for this PoC. Use only tools provided in the request.\n</available_skills>",
+    });
+  }
+  return wire;
+}

package/src/core/inference/retry.ts

@@ -0,0 +1,68 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { awaitWithSignal, RPCError } from "../protocol/transport.ts";
+
+const CREATION_ATTEMPTS = 5;
+const RECOVERY_ATTEMPTS = 3;
+const INITIAL_INTERVAL_MS = 2000;
+const MAX_INTERVAL_MS = 60_000;
+const RETRYABLE_HTTP_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const RETRYABLE_CONNECT_CODES = new Set(["resource_exhausted", "deadline_exceeded", "internal", "unavailable"]);
+
+export interface InferenceRetryRuntime {
+  random?: () => number;
+  wait?: (delayMs: number, signal: AbortSignal) => Promise<void>;
+}
+
+export interface InferenceRetryEvent {
+  phase: "creation" | "recovery";
+  nextAttempt: number;
+  limit: number;
+  delayMs: number;
+}
+
+/** Backoff: starts at 2 s, doubles, jitter factor 0.5. The elapsed-time cap is disabled. */
+export function inferenceRetryDelayMs(retryIndex: number, random: number): number {
+  if (!Number.isInteger(retryIndex) || retryIndex < 0 || retryIndex >= CREATION_ATTEMPTS - 1) throw new Error("Invalid retry index.");
+  if (!Number.isFinite(random) || random < 0 || random >= 1) throw new Error("The retry random value must be at least 0 and below 1.");
+  const intervalMs = Math.min(INITIAL_INTERVAL_MS * 2 ** retryIndex, MAX_INTERVAL_MS);
+  const intervalNanos = intervalMs * 1_000_000;
+  return Math.floor((intervalNanos * 0.5 + random * (intervalNanos + 1)) / 1_000_000);
+}
+
+function canRetryCreation(error: unknown): boolean {
+  return error instanceof RPCError && error.httpStatus !== undefined && RETRYABLE_HTTP_STATUSES.has(error.httpStatus);
+}
+
+function canRecover(error: unknown): boolean {
+  return canRetryCreation(error) || (error instanceof RPCError && error.httpStatus === undefined && RETRYABLE_CONNECT_CODES.has(error.code));
+}
+
+/** Makes each attempt build a new request, separate from the same-body resend of the 415/compression fallback. */
+export async function withInferenceRetries<T>(
+  request: (isRecovery: boolean) => Promise<T>,
+  options: { signal: AbortSignal; runtime?: InferenceRetryRuntime; onRetry?: (event: InferenceRetryEvent) => void },
+): Promise<T> {
+  const { signal, runtime = {} } = options;
+  const random = runtime.random ?? Math.random;
+  const wait = runtime.wait ?? ((delayMs: number, signal: AbortSignal) => delay(delayMs, undefined, { signal }));
+  let lastError: unknown;
+  for (let recovery = 0; recovery < RECOVERY_ATTEMPTS; recovery++) {
+    for (let attempt = 0; attempt < CREATION_ATTEMPTS; attempt++) {
+      signal.throwIfAborted();
+      try { return await request(recovery > 0); }
+      catch (error) {
+        signal.throwIfAborted();
+        if (!canRecover(error)) throw error;
+        lastError = error;
+        if (!canRetryCreation(error) || attempt + 1 === CREATION_ATTEMPTS) break;
+        const delayMs = inferenceRetryDelayMs(attempt, random());
+        options.onRetry?.({ phase: "creation", nextAttempt: attempt + 2, limit: CREATION_ATTEMPTS, delayMs });
+        try { await awaitWithSignal(wait(delayMs, signal), signal); }
+        catch (error) { signal.throwIfAborted(); throw error; }
+      }
+    }
+    signal.throwIfAborted();
+    if (recovery + 1 < RECOVERY_ATTEMPTS) options.onRetry?.({ phase: "recovery", nextAttempt: recovery + 2, limit: RECOVERY_ATTEMPTS, delayMs: 0 });
+  }
+  throw lastError;
+}

package/src/core/inference/state.ts

@@ -0,0 +1,8 @@
+export const MAX_STEP_INDEX = 2_147_483_647;
+
+export interface StepState { nextStepIndex: number }
+
+export function takeStep(state: StepState): number {
+  if (state.nextStepIndex >= MAX_STEP_INDEX) throw new Error("The session step limit was exceeded.");
+  return state.nextStepIndex++;
+}

package/src/core/models/access.ts

@@ -0,0 +1,7 @@
+import type { JsonObject, ModelInfo } from "../types.ts";
+
+/** When the server provides a separate allowlist, it is applied together with the catalog's disabled flags. */
+export function applyTeamModelPolicy(models: ModelInfo[], team: JsonObject): void {
+  const allowed = Array.isArray(team.allowedModelUids) ? team.allowedModelUids.filter((id): id is string => typeof id === "string") : [];
+  if (allowed.length) for (const model of models) model.isDisabled ||= !allowed.includes(model.id);
+}

package/src/core/models/catalog.ts

@@ -0,0 +1,35 @@
+import { object, requiredString, tokenCount, type JsonObject, type ModelInfo } from "../types.ts";
+
+export interface ModelCatalog { raw: JsonObject; models: ModelInfo[]; defaultModelUid?: string }
+
+export function parseModelCatalog(response: JsonObject): ModelCatalog {
+  if (!Array.isArray(response.clientModelConfigs)) throw new Error("clientModelConfigs is missing.");
+  const override = object(response.defaultOverrideModelConfig ?? {}, "defaultOverrideModelConfig");
+  const defaultModelUid = typeof override.modelUid === "string" ? override.modelUid : undefined;
+  const models = response.clientModelConfigs.map((value) => {
+    const config = object(value, "ClientModelConfig");
+    const info = object(config.modelInfo, "modelInfo");
+    const features = object(info.modelFeatures ?? {}, "modelFeatures");
+    const family = object(config.modelFamilyMetadata ?? {}, "modelFamilyMetadata");
+    return {
+      id: requiredString(config.modelUid, "modelUid"),
+      name: requiredString(config.label, "label"),
+      contextWindow: tokenCount(info.maxTokens ?? 0, "context window"),
+      maxOutputTokens: tokenCount(info.maxOutputTokens ?? 0, "max output tokens"),
+      supportsThinking: features.supportsThinking === true,
+      supportsImages: config.supportsImages === true || features.supportsImages === true,
+      supportsToolCalls: features.supportsToolCalls === true,
+      supportsParallelToolCalls: features.supportsParallelToolCalls === true,
+      isRouter: info.isModelRouter === true,
+      isDisabled: config.disabled === true,
+      familyId: typeof info.modelFamilyUid === "string" ? info.modelFamilyUid : undefined,
+      aliases: Array.isArray(info.aliases) ? info.aliases.filter((value): value is string => typeof value === "string") : [],
+      isDefaultInFamily: config.isDefaultModelInFamily === true || family.isDefaultModelInFamily === true,
+      isRecommended: config.isRecommended === true,
+      costTier: typeof config.modelCostTier === "string" ? config.modelCostTier : undefined,
+      creditMultiplier: typeof config.creditMultiplier === "number" ? config.creditMultiplier : undefined,
+      pricingType: typeof config.pricingType === "string" ? config.pricingType : undefined,
+    };
+  });
+  return { raw: response, models, defaultModelUid };
+}

package/src/core/models/index.ts

@@ -0,0 +1,4 @@
+export { getModelByUID, selectModel } from "./select.ts";
+export { parseModelCatalog, type ModelCatalog } from "./catalog.ts";
+export { EFFECTIVE_THINKING_LEVELS, groupModelID, modelIDForUID, projectModelVariants, restoreModelVariants, resolveBackendSelection } from "./variants.ts";
+export type { EffectiveThinkingLevel, ModelDimension, ModelVariant, VariantGroup, VariantProjection, BackendModelSelection } from "./variants.ts";

package/src/core/models/select.ts

@@ -0,0 +1,43 @@
+import type { ModelInfo } from "../types.ts";
+
+/** Saved sessions and AssignModel results are already-resolved UIDs, not selectors. */
+export function getModelByUID(models: readonly ModelInfo[], uid: string): ModelInfo {
+  const model = models.find((entry) => entry.id === uid);
+  if (!model) throw new Error(`${uid} is not in the model list. It is not replaced with another model automatically.`);
+  if (model.isDisabled) throw new Error(`Model is disabled: ${uid}`);
+  return model;
+}
+
+/** Resolves user selectors to match the CLI's selector semantics. The caller picks the default first. */
+export function selectModel(models: readonly ModelInfo[], selector: string): ModelInfo {
+  const normalize = (name: string) => name.trim().toLowerCase().replaceAll(" ", "-");
+  const tokenize = (name: string): string[] => name.toLowerCase().match(/[a-z]+|[0-9]+/g) ?? [];
+  const query = normalize(selector);
+  if (!query) throw new Error("The model name is empty.");
+
+  // Families take precedence over aliases. An alias points to a family, not a declared variant.
+  const family = models.find((model) => model.familyId && normalize(model.familyId) === query)
+    ?? models.find((model) => model.aliases?.some((alias) => normalize(alias) === query));
+  if (family) {
+    const selected = models.find((model) => !model.isDisabled
+      && (family.familyId ? model.familyId === family.familyId : model.id === family.id));
+    if (!selected) throw new Error(`Model is disabled: ${selector}`);
+    return selected;
+  }
+
+  const exact = models.find((model) => normalize(model.id) === query)
+    ?? models.find((model) => normalize(model.name) === query);
+  if (exact) return getModelByUID(models, exact.id);
+
+  // Compares whole alphanumeric tokens in any order, not arbitrary substrings.
+  const words = tokenize(query);
+  const candidates = words.some((word) => /[a-z]/.test(word))
+    ? models.filter((model) => !model.isDisabled)
+      .map((model) => ({ model, tokens: tokenize(model.id) }))
+      .filter(({ tokens }) => words.every((word) => tokens.includes(word)))
+    : [];
+  candidates.sort((left, right) => left.tokens.length - right.tokens.length
+    || (left.model.id < right.model.id ? 1 : left.model.id > right.model.id ? -1 : 0));
+  if (candidates[0]) return candidates[0].model;
+  throw new Error(`Model unavailable: ${selector}`);
+}

package/src/core/models/variants.ts

@@ -0,0 +1,163 @@
+import { object, requiredString, tokenCount, type JsonObject, type ModelInfo } from "../types.ts";
+import { parseModelCatalog, type ModelCatalog } from "./catalog.ts";
+import { getModelByUID } from "./select.ts";
+
+export const EFFECTIVE_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type EffectiveThinkingLevel = typeof EFFECTIVE_THINKING_LEVELS[number];
+export interface ModelDimension { key: string; order: number; name: string }
+export interface ModelVariant {
+  model: ModelInfo;
+  family: string;
+  familyName: string;
+  dimensions: ModelDimension[];
+  level?: EffectiveThinkingLevel;
+  unsupported?: string;
+  /** Only the model fields the persistent cache needs. Never the whole raw response or auth metadata. */
+  config: JsonObject;
+}
+export interface VariantGroup {
+  id: string;
+  family: string;
+  name: string;
+  dimensions: ModelDimension[];
+  variants: ModelVariant[];
+  mappings: Partial<Record<EffectiveThinkingLevel, string>>;
+  canPublish: boolean;
+  reason?: string;
+}
+export interface VariantProjection {
+  variants: ModelVariant[];
+  groups: VariantGroup[];
+  unsupported: { uid: string; reason: string }[];
+}
+export interface BackendModelSelection { uid: string; model: ModelInfo; level: EffectiveThinkingLevel; variant: ModelVariant }
+const strengthNames = new Map<string, EffectiveThinkingLevel>([
+  ["None", "off"], ["No Thinking", "off"], ["Minimal", "minimal"], ["Low", "low"],
+  ["Medium", "medium"], ["High", "high"], ["XHigh", "xhigh"], ["Max", "max"],
+]);
+const thinkingDimensions = new Set(["Reasoning Effort", "Effort", "Thinking"]);
+
+export function modelIDForUID(uid: string): string { return "uid:" + encodeURIComponent(uid); }
+export function groupModelID(family: string, dimensions: readonly ModelDimension[]): string {
+  const key = JSON.stringify(dimensions.map(({ key, order, name }) => [key, order, name]));
+  return "family:" + encodeURIComponent(family) + (dimensions.length ? ":" + Buffer.from(key).toString("base64url") : "");
+}
+
+function dimensionsOf(config: JsonObject): ModelDimension[] {
+  const family = object(config.modelFamilyMetadata ?? {}, "modelFamilyMetadata");
+  if (family.entries === undefined) return [];
+  if (!Array.isArray(family.entries)) throw new Error("Model dimension entries are not an array.");
+  const seen = new Set<string>();
+  return family.entries.map((item) => {
+    const entry = object(item, "model dimension"), value = object(entry.value ?? {}, "dimension value");
+    const key = requiredString(entry.key, "dimension key");
+    if (seen.has(key)) throw new Error(`Duplicate model dimension: ${key}`);
+    seen.add(key);
+    const order = tokenCount(value.order ?? 0, "dimension order");
+    if (!Number.isSafeInteger(order)) throw new Error("The model dimension order must be an integer.");
+    return { key, order, name: typeof value.name === "string" ? value.name : "" };
+  }).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+}
+
+function classify(model: ModelInfo, dimensions: readonly ModelDimension[]): Pick<ModelVariant, "level" | "unsupported"> {
+  if (model.isDisabled) return { unsupported: "disabled" };
+  if (model.isRouter) return { unsupported: "router contract not established for Pi" };
+  if (model.contextWindow <= 0 || model.maxOutputTokens <= 0) return { unsupported: "missing context/output limit" };
+  const thinking = dimensions.find((entry) => entry.key === "Thinking");
+  const effort = dimensions.filter((entry) => entry.key === "Reasoning Effort" || entry.key === "Effort");
+  if (effort.length > 1) return { unsupported: "ambiguous thinking dimensions" };
+  if (thinking?.order === 0 && !model.supportsThinking) return { level: "off" };
+  const level = effort[0] && strengthNames.get(effort[0].name);
+  if (level) return { level };
+  if (!effort.length && !thinking && !model.supportsThinking) return { level: "off" };
+  return { unsupported: "thinking strength metadata is unknown" };
+}
+
+function sanitizedConfig(config: JsonObject, model: ModelInfo, familyName: string, dimensions: readonly ModelDimension[]): JsonObject {
+  const info = object(config.modelInfo, "modelInfo");
+  return {
+    modelUid: model.id, label: model.name, disabled: model.isDisabled, maxTokens: model.contextWindow,
+    supportsImages: model.supportsImages,
+    // The recommended flag must survive offline restore so the list filter gives the same result.
+    ...(model.isRecommended ? { isRecommended: true } : {}),
+    modelInfo: {
+      modelUid: model.id, modelFamilyUid: model.familyId || model.id,
+      maxTokens: model.contextWindow, maxOutputTokens: model.maxOutputTokens,
+      ...(typeof info.modelType === "string" ? { modelType: info.modelType } : {}),
+      isModelRouter: model.isRouter, aliases: [...(model.aliases ?? [])],
+      modelFeatures: {
+        supportsImages: model.supportsImages, supportsToolCalls: model.supportsToolCalls,
+        supportsParallelToolCalls: model.supportsParallelToolCalls, supportsThinking: model.supportsThinking,
+      },
+    },
+    modelFamilyMetadata: { modelFamilyLabel: familyName, entries: dimensions.map(({ key, order, name }) => ({ key, value: { order, name } })) },
+  };
+}
+
+function capabilityKey(model: ModelInfo): string {
+  return JSON.stringify([model.contextWindow, model.maxOutputTokens, model.supportsImages, model.supportsToolCalls, model.supportsParallelToolCalls]);
+}
+
+export function projectModelVariants(catalog: ModelCatalog): VariantProjection {
+  const configs = catalog.raw.clientModelConfigs;
+  if (!Array.isArray(configs) || configs.length !== catalog.models.length) throw new Error("The raw and projected model lists do not match.");
+  const ids = new Set<string>();
+  const variants = catalog.models.map((original, index): ModelVariant => {
+    if (ids.has(original.id)) throw new Error(`Duplicate model UID: ${original.id}`);
+    ids.add(original.id);
+    const config = object(configs[index], "model config"), info = object(config.modelInfo, "modelInfo");
+    if (config.modelUid !== original.id) throw new Error("Model UIDs do not match the raw order.");
+    const allDimensions = dimensionsOf(config);
+    const family = object(config.modelFamilyMetadata ?? {}, "modelFamilyMetadata");
+    const model = { ...original, aliases: [...(original.aliases ?? [])], contextWindow: tokenCount(config.maxTokens ?? original.contextWindow, "context window") };
+    const familyName = typeof family.modelFamilyLabel === "string" && family.modelFamilyLabel ? family.modelFamilyLabel : model.familyId || model.name;
+    const classification = typeof info.modelType === "string" && info.modelType !== "MODEL_TYPE_CHAT"
+      ? { unsupported: "not a chat model" } : classify(model, allDimensions);
+    return {
+      model, family: model.familyId || model.id, familyName,
+      dimensions: allDimensions.filter((entry) => !thinkingDimensions.has(entry.key)), ...classification,
+      config: sanitizedConfig(config, model, familyName, allDimensions),
+    };
+  });
+  const groupMap = new Map<string, VariantGroup>();
+  for (const variant of variants) {
+    const id = groupModelID(variant.family, variant.dimensions);
+    let group = groupMap.get(id);
+    if (!group) {
+      group = { id, family: variant.family, name: variant.familyName, dimensions: variant.dimensions, variants: [], mappings: {}, canPublish: true };
+      groupMap.set(id, group);
+    }
+    group.variants.push(variant);
+    if (variant.level === undefined || variant.unsupported) continue;
+    if (group.mappings[variant.level]) { group.canPublish = false; group.reason = "ambiguous UID for thinking level"; }
+    else group.mappings[variant.level] = variant.model.id;
+  }
+  for (const group of groupMap.values()) {
+    const supported = group.variants.filter((variant) => variant.level !== undefined && !variant.unsupported);
+    if (!supported.length) { group.canPublish = false; group.reason = "no verified thinking mapping"; }
+    else if (new Set(supported.map((variant) => capabilityKey(variant.model))).size !== 1) {
+      group.canPublish = false; group.reason = "variant capabilities differ; use exact UID";
+    }
+  }
+  return { variants, groups: [...groupMap.values()], unsupported: variants.filter((variant) => variant.unsupported).map((variant) => ({ uid: variant.model.id, reason: variant.unsupported! })) };
+}
+
+export function restoreModelVariants(configs: readonly JsonObject[]): VariantProjection {
+  return projectModelVariants(parseModelCatalog({ clientModelConfigs: [...configs] }));
+}
+
+/** Accepts only the effective level that Pi already clamped or selected. Never falls back to an alias, price or default model. */
+export function resolveBackendSelection(projection: VariantProjection, modelID: string, level: EffectiveThinkingLevel): BackendModelSelection {
+  if (!EFFECTIVE_THINKING_LEVELS.includes(level)) throw new Error(`Unsupported thinking level: ${level}`);
+  let variant = projection.variants.find((entry) => modelIDForUID(entry.model.id) === modelID);
+  if (variant) {
+    if (variant.unsupported || variant.level !== level) throw new Error(`This exact UID does not support the requested thinking level: ${modelID} (${level})`);
+  } else {
+    const group = projection.groups.find((entry) => entry.id === modelID);
+    const uid = group?.canPublish ? group.mappings[level] : undefined;
+    if (!uid) throw new Error(`Model or thinking level unavailable: ${modelID} (${level})`);
+    variant = projection.variants.find((entry) => entry.model.id === uid)!;
+  }
+  const model = getModelByUID(projection.variants.map((entry) => entry.model), variant.model.id);
+  return { uid: model.id, model, level, variant };
+}