Skip to content

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

14.9 KB
Raw Blame
/**
 * Model Parser - Unified syntax for provider@model:concurrency
 *
 * New syntax: provider@model[:concurrency]
 * Examples:
 *   openrouter@<vendor>/<model>  - Explicit OpenRouter
 *   google@<model>               - Direct Google API
 *   g@<model>                    - Direct Google API (shortcut)
 *   ollama@<model>:3             - Ollama with concurrency 3
 *   ollama@<model>:0             - Ollama with no limits
 *   oc/<model>                   - Legacy prefix syntax (explicit, deprecated)
 *
 * Provider shortcuts (case-insensitive) are each definition's `shortcuts` in
 * BUILTIN_PROVIDERS ({@link PROVIDER_SHORTCUTS}); `claudish --help` lists them.
 *
 * A name with no provider is not ROUTED here. The parser's answer only decides
 * whether it reaches `route()`, which calculates the chain from the user's rules
 * and the cloud models catalog; `proxyRouteDecision` (native-route.ts) is that
 * gate. What each form parses to:
 *   URL, `provider@model`, legacy prefix -> that provider, explicit: no chain
 *   a `nativeModelPatterns` match        -> that provider, a known `vendor/`
 *                                           stripped (`openai/<id>` → `<id>`);
 *                                           not explicit, so still routed
 *   `anthropic/<id>`                     -> native-anthropic; the proxy sends the
 *                                           id to OpenRouter verbatim
 *   `poe:<id>`                           -> poe; the proxy's Poe step serves it
 *   an unknown `vendor/`                 -> `unknown`; routed
 *   Claude Code's own names (`opus`, `claude-*`), `""`, `@model`
 *                                        -> native-anthropic: Claude Code's own
 *                                           auth, never routed
 *   anything else (`o4-mini`)            -> {@link AUTO_ROUTE_PROVIDER}; routed
 */

/**
 * The parser's answer for a bare name it cannot attribute to anyone: no `/`, no
 * native pattern matched, and not a name Claude Code owns (`o4-mini`,
 * `no-such-model-xyz`). It is NOT a claudish provider, and nothing may look it up
 * as one: `route()` decides which provider serves the name, from the user's rules
 * and the cloud models catalog.
 *
 * Why not `"unknown"`: that value already means "a `vendor/` with no known vendor"
 * (`foo/bar`) to `getMissingKeyError` and the advisor label, and it keeps that
 * meaning. `auto-route` is the code's existing word for "routing chooses" (the
 * stats invocation mode), and no provider or provider shortcut carries the name.
 */
export const AUTO_ROUTE_PROVIDER = "auto-route";

/**
 * Parsed model specification
 */
export interface ParsedModel {
  /**
   * Normalized provider name (lowercase). For a name with no explicit provider
   * this may also be one of the parser's own values, none of them a provider:
   * `custom-url`, `unknown` (a `vendor/` with no known vendor), or
   * {@link AUTO_ROUTE_PROVIDER} (a bare name `route()` decides).
   */
  provider: string;
  /** Model name/ID (without provider prefix) */
  model: string;
  /** Original full model string */
  original: string;
  /** Concurrency limit for local providers (undefined = use default, 0 = no limit) */
  concurrency?: number;
  /** Whether this used legacy syntax (for deprecation warnings) */
  isLegacySyntax: boolean;
  /** Whether provider was explicitly specified (vs auto-detected) */
  isExplicitProvider: boolean;
  /** `+pro` / `+standard` on the spec (removed from `model`). See `wire-markers.ts`. */
  mode?: WireMode;
  /** `#<speed>` on the spec (removed from `model`). */
  speed?: WireSpeed;
}

/**
 * Provider shortcut mappings — derived from BUILTIN_PROVIDERS.
 * Re-exported for backward compatibility.
 */
import { isClaudeCodeModelName } from "./claude-code-aliases.js";
import {
  getLegacyPrefixPatterns as _getLegacyPrefixPatterns,
  getNativeModelPatterns as _getNativeModelPatterns,
  getShortcuts as _getShortcuts,
  isDirectApiProvider as _isDirectApiProvider,
  isLocalTransport,
} from "./provider-definitions.js";
import { type WireMarkers, splitWireMarkers } from "./wire-markers.js";
import type { WireMode, WireSpeed } from "./wire-request.js";

export const PROVIDER_SHORTCUTS: Record<string, string> = _getShortcuts();

/**
 * Local providers (no API key needed) — derived from BUILTIN_PROVIDERS.
 */
export const LOCAL_PROVIDERS = {
  has(name: string): boolean {
    return isLocalTransport(name);
  },
};

/**
 * Providers that support direct API access — derived from BUILTIN_PROVIDERS.
 */
export const DIRECT_API_PROVIDERS = {
  has(name: string): boolean {
    return _isDirectApiProvider(name);
  },
};

/**
 * Native model prefixes — derived from BUILTIN_PROVIDERS.
 */
export const NATIVE_MODEL_PATTERNS = _getNativeModelPatterns();

/**
 * Legacy prefix patterns — derived from BUILTIN_PROVIDERS.
 */
export const LEGACY_PREFIX_PATTERNS = _getLegacyPrefixPatterns();

/**
 * Separator for a ROUTE CHAIN — an ordered list of explicit specs to try in turn:
 *
 *   [email protected][email protected]+or@minimax/minimax-m2.5
 *
 * Why a chain form exists at all: `team` and `create_session` spawn child
 * claudish processes with an EXPLICIT spec rather than the bare name, because a
 * bare name makes the child re-resolve credentials and open its own 1Password SDK
 * client — and that handshake is arbitrated machine-wide, so N children racing it
 * means N-1 denials or N sequential dialogs (see `auth/credentials/prehydrate.ts`).
 * Explicitness is what buys one dialog per run. But an explicit spec is also a
 * chain of ONE, so those children had no fallback: `isRetryableError` is reachable
 * only from `FallbackHandler`, which is only built for a name the child routes
 * itself. A spent subscription, a rotated key, or a capability rejection killed the
 * model outright, where the same request served interactively would have fallen
 * through. This form carries the parent's whole chain across the process boundary
 * with every element still explicit, so both properties hold at once.
 *
 * `+` rather than `,` (already the advisor/team list separator) or `|` (needs shell
 * quoting when a user copies a spawn line out of a log). Verified against the live
 * catalog: 0 of 764 model ids contain a `+`.
 */
export const MODEL_CHAIN_SEPARATOR = "+";

/**
 * Split a `--model` value into its ordered candidates.
 *
 * A string with no separator yields a one-element array, so callers can treat
 * every model value as a chain without branching. Empty segments are dropped —
 * a trailing separator is a formatting artifact, not a request for a null
 * candidate.
 */
export function parseModelChain(modelSpec: string): string[] {
  const parts = modelSpec
    .split(MODEL_CHAIN_SEPARATOR)
    .map((s) => s.trim())
    .filter(Boolean);
  // `+` also marks a request mode (`cx@gpt-6-sol+pro`, see `wire-markers.ts`).
  // A segment that is ONLY a mode word, optionally followed by `#<speed>` or
  // `:N`, is that marker on the spec before it, never a chain element: every
  // element a chain carries is an explicit `provider@model` spec.
  const merged: string[] = [];
  for (const part of parts) {
    if (merged.length > 0 && MODE_MARKER_SEGMENT.test(part)) {
      merged[merged.length - 1] = `${merged[merged.length - 1]}+${part}`;
    } else {
      merged.push(part);
    }
  }
  return merged.length > 0 ? merged : [modelSpec];
}

const MODE_MARKER_SEGMENT = /^(pro|standard)(#[a-z]+)?(:\d+)?$/i;

/**
 * True when a model spec routes to the raw-URL `custom-url` provider: some element of
 * its chain (`a+b+c`) resolves to `custom-url` (`https://host/…`, `custom-url@https://…`),
 * so claudish would connect to the host in the spec. Parsed with `parseModelSpec` itself,
 * not a prefix test, so it stays faithful to what routing does.
 *
 * The ONE check for a model chosen by a checkout rather than by the user: a working
 * directory's `.env` (`dotenv-allowlist.ts`) and a project `.claudish.json` profile
 * (`project-models.ts`) both refuse such a spec.
 */
export function modelSpecNamesRawUrl(modelSpec: string): boolean {
  return parseModelChain(modelSpec).some(
    (element) => parseModelSpec(element.trim()).provider === "custom-url"
  );
}

/**
 * Parse a model specification string
 *
 * Supports both new and legacy syntax:
 * - New: provider@model[:concurrency]
 * - Legacy: prefix/model or prefix:model
 *
 * NOTE: this parses ONE spec. A chain value (`a+b+c`) must be split with
 * {@link parseModelChain} first — the CLI does that at the argument boundary, so
 * everything downstream of arg parsing still sees a single spec.
 *
 * @param modelSpec - The model specification string
 * @returns Parsed model information
 */
export function parseModelSpec(modelSpec: string): ParsedModel {
  // Mode and speed markers are not part of any model id: strip them first, so
  // every consumer (routing, --probe, validation) sees the model alone. An
  // invalid marker is left in place and fails as an unknown model, or is
  // refused with its own message by the proxy, which splits markers strictly.
  let markers: WireMarkers | undefined;
  try {
    markers = splitWireMarkers(modelSpec);
  } catch {
    markers = undefined;
  }
  if (markers && (markers.mode || markers.speed)) {
    const parsed = parseModelSpecWithoutMarkers(markers.spec);
    return {
      ...parsed,
      original: modelSpec,
      ...(markers.mode ? { mode: markers.mode } : {}),
      ...(markers.speed ? { speed: markers.speed } : {}),
    };
  }
  return parseModelSpecWithoutMarkers(modelSpec);
}

function parseModelSpecWithoutMarkers(modelSpec: string): ParsedModel {
  const original = modelSpec;

  // Check for URL-style model (http:// or https://)
  if (modelSpec.startsWith("http://") || modelSpec.startsWith("https://")) {
    // `custom-url` is a raw-URL provider: claudish connects to the host in the spec. The
    // credential authority has no notion of where a model spec came from, so it cannot
    // deny a repo-chosen host on its own. The guarantee that a spec reaching here was not
    // chosen by an unreviewed checkout is enforced at the two places a checkout can name
    // a model, both through `modelSpecNamesRawUrl`: the working directory's `.env`
    // (`dotenv-allowlist.ts` refuses a `CLAUDISH_MODEL`/`CLAUDISH_MODEL_*` that resolves to
    // `custom-url`) and a project `.claudish.json` profile (`project-models.ts` drops such
    // a tier). A custom URL model must come from the shell, a flag or the user's own config.
    return {
      provider: "custom-url",
      model: modelSpec,
      original,
      isLegacySyntax: false,
      isExplicitProvider: true,
    };
  }

  // Check for new @ syntax: provider@model[:concurrency]
  const atMatch = modelSpec.match(/^([^@]+)@(.+)$/);
  if (atMatch) {
    const providerPart = atMatch[1].toLowerCase();
    let modelPart = atMatch[2];
    let concurrency: number | undefined;

    // Check for concurrency suffix on local providers
    const concurrencyMatch = modelPart.match(/^(.+):(\d+)$/);
    if (concurrencyMatch) {
      modelPart = concurrencyMatch[1];
      concurrency = Number.parseInt(concurrencyMatch[2], 10);
    }

    // Resolve provider shortcut
    const provider = PROVIDER_SHORTCUTS[providerPart] || providerPart;

    return {
      provider,
      model: modelPart,
      original,
      concurrency,
      isLegacySyntax: false,
      isExplicitProvider: true,
    };
  }

  // Check for legacy prefix patterns
  const lowerSpec = modelSpec.toLowerCase();
  for (const { prefix, provider, stripPrefix } of LEGACY_PREFIX_PATTERNS) {
    if (lowerSpec.startsWith(prefix)) {
      const model = stripPrefix ? modelSpec.slice(prefix.length) : modelSpec;

      // Check for concurrency suffix on local providers
      let concurrency: number | undefined;
      let modelName = model;
      if (LOCAL_PROVIDERS.has(provider)) {
        const concurrencyMatch = model.match(/^(.+):(\d+)$/);
        if (concurrencyMatch) {
          modelName = concurrencyMatch[1];
          concurrency = Number.parseInt(concurrencyMatch[2], 10);
        }
      }

      return {
        provider,
        model: modelName,
        original,
        concurrency,
        isLegacySyntax: true,
        isExplicitProvider: true,
      };
    }
  }

  // No explicit provider - try to detect native provider from model name
  for (const { pattern, provider } of NATIVE_MODEL_PATTERNS) {
    if (pattern.test(modelSpec)) {
      // For patterns that match "provider/model", strip the provider prefix
      const slashIndex = modelSpec.indexOf("/");
      const model = slashIndex > 0 ? modelSpec.slice(slashIndex + 1) : modelSpec;

      return {
        provider,
        model,
        original,
        isLegacySyntax: false,
        isExplicitProvider: false,
      };
    }
  }

  // Unknown vendor/model format - require explicit provider
  // Use openrouter@vendor/model if you want OpenRouter
  if (modelSpec.includes("/")) {
    return {
      provider: "unknown",
      model: modelSpec,
      original,
      isLegacySyntax: false,
      isExplicitProvider: false,
    };
  }

  // No "/" and no pattern matched. Claude Code's own names (`opus`, `opusplan`,
  // `sonnet[1m]`, `best`) are served on its own auth by the native passthrough.
  // `""` and `@model` are not model names at all: they keep the native answer
  // they always had, and the harness rejects them. Every other bare name
  // (`o4-mini`, a typo) is routed: the native passthrough serves none of them,
  // so sending one there only ever earned an Anthropic 404.
  return {
    provider: lastResortProvider(modelSpec),
    model: modelSpec,
    original,
    isLegacySyntax: false,
    isExplicitProvider: false,
  };
}

/**
 * The provider for a bare name no `/` and no pattern claimed: native-anthropic
 * for Claude Code's names and for `""` / `@model`, else {@link AUTO_ROUTE_PROVIDER}.
 * Trimmed, as `isClaudeCodeModelName` is, so a whitespace-only value counts as
 * empty.
 */
function lastResortProvider(modelSpec: string): string {
  const name = modelSpec.trim();
  const isNative = name === "" || name.startsWith("@") || isClaudeCodeModelName(name);
  return isNative ? "native-anthropic" : AUTO_ROUTE_PROVIDER;
}

/**
 * Check if a provider is a local provider
 */
export function isLocalProviderName(provider: string): boolean {
  return LOCAL_PROVIDERS.has(provider.toLowerCase());
}

/**
 * Check if a provider supports direct API access
 */
export function isDirectApiProvider(provider: string): boolean {
  return DIRECT_API_PROVIDERS.has(provider.toLowerCase());
}

/**
 * Get deprecation warning for legacy syntax
 */
export function getLegacySyntaxWarning(parsed: ParsedModel): string | null {
  if (!parsed.isLegacySyntax) {
    return null;
  }

  const newSyntax = `${parsed.provider}@${parsed.model}`;
  return (
    `Deprecation warning: "${parsed.original}" uses legacy prefix syntax.\n` +
    `  Consider using: ${newSyntax}`
  );
}

/**
 * Format a model spec in the new syntax
 */
export function formatModelSpec(provider: string, model: string, concurrency?: number): string {
  let spec = `${provider}@${model}`;
  if (concurrency !== undefined) {
    spec += `:${concurrency}`;
  }
  return spec;
}