Skip to content

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

17.1 KB
Raw Blame
/**
 * Build the handler for a catalog connection from its `wire` and the route
 * registry (catalog 3.7.0): the API comes from `wire.api`, the URL from the
 * registry, and each request's output limit, reasoning, mode and speed from the
 * wire (`ComposedHandler` step 5w). A provider's own transport is kept only for
 * what is the provider's: authentication, identity headers and extra fields.
 *
 * Out of scope, and left to their own profiles: the dynamic subscriptions
 * (`gk@`, `ag@`, `dv@`), whose account decides what they serve and whose
 * connections the catalog publishes as `unknown`; Vertex, whose project is the
 * user's; and every provider without a route binding (local, LiteLLM, custom
 * endpoints).
 */
import type { Context } from "hono";
import { AnthropicAPIFormat } from "../adapters/anthropic-api-format.js";
import type { BaseAPIFormat } from "../adapters/base-api-format.js";
import { CodexAPIFormat } from "../adapters/codex-api-format.js";
import { GeminiAPIFormat } from "../adapters/gemini-api-format.js";
import { OpenAIAPIFormat } from "../adapters/openai-api-format.js";
import { OpenRouterAPIFormat } from "../adapters/openrouter-api-format.js";
import { ComposedHandler } from "../handlers/composed-handler.js";
import { wrapAnthropicError } from "../handlers/shared/anthropic-error.js";
import type { RemoteProvider } from "../handlers/shared/remote-provider-types.js";
import type { ModelHandler } from "../handlers/types.js";
import { log } from "../logger.js";
import { ensureRouteRegistryReady } from "./catalog-client.js";
import {
  type ResolvedConnection,
  connectionBaseUrl,
  resolveConnection,
  resolveRouteProfile,
} from "./connection-resolver.js";
import { type KnownWire, type WireApi, wireRequestUrl } from "./connection-wire.js";
import { MUSE_CODE_BASE_URL } from "./meta-muse/muse-mint.js";
import { getProviderByName } from "./provider-definitions.js";
import type { ProfileContext } from "./provider-profiles.js";
import { AnthropicProviderTransport } from "./transport/anthropic-compat.js";
import { GeminiProviderTransport } from "./transport/gemini-apikey.js";
import { MuseCodeTransport } from "./transport/meta-muse-code.js";
import { OpenAICodexTransport } from "./transport/openai-codex.js";
import { OpenAIProviderTransport } from "./transport/openai.js";
import { OpenCodeZenMessagesTransport, OpenCodeZenTransport } from "./transport/opencode-zen.js";
import { OpenRouterProviderTransport } from "./transport/openrouter.js";
import { PoeProvider } from "./transport/poe.js";
import type { ProviderTransport } from "./transport/types.js";
import { TryInTurnHandler, apiOnlyWire } from "./wire-try-in-turn.js";

/** Providers whose requests are NOT built from catalog wires (see the header). */
const NOT_WIRE_ROUTED = new Set(["grok-subscription", "antigravity", "devin", "vertex"]);

const OPENCODE = new Set(["opencode-zen", "opencode-zen-go"]);

/**
 * The base URL a request goes to: the registry's, unless the user overrode the
 * provider's base URL (env or config), which is kept and logged. An override
 * with no path keeps the registry's path (`https://api.minimaxi.com` +
 * `/anthropic/v1`); one with a path is used as the whole base.
 */
export function effectiveBaseUrl(
  registryBaseUrl: string,
  definitionBaseUrl: string | undefined,
  resolvedBaseUrl: string | undefined
): { baseUrl: string; overridden: boolean } {
  if (!resolvedBaseUrl || !definitionBaseUrl || resolvedBaseUrl === definitionBaseUrl) {
    return { baseUrl: registryBaseUrl, overridden: false };
  }
  try {
    const override = new URL(resolvedBaseUrl);
    if (override.pathname === "/" || override.pathname === "") {
      return {
        baseUrl: `${override.origin}${new URL(registryBaseUrl).pathname}`,
        overridden: true,
      };
    }
  } catch {
    return { baseUrl: registryBaseUrl, overridden: false };
  }
  return { baseUrl: resolvedBaseUrl.replace(/\/+$/, ""), overridden: true };
}

/** The registry base, except Muse Code's credentials must stay on the pinned host. */
function requestBaseUrl(connection: ResolvedConnection, api: WireApi): string | undefined {
  return connection.provider === "meta-muse-code"
    ? `${MUSE_CODE_BASE_URL}/v1`
    : connectionBaseUrl(connection, api);
}

/**
 * One line saying how a connection is called, for `--probe`: the API and URL,
 * the output-limit field, the reasoning encoding, and the modes and speeds it
 * offers. Every part is the wire's own value or its status, never derived.
 */
export function describeConnectionWire(connection: ResolvedConnection): string {
  const where = `${connection.route.routeId}/${connection.route.routeProfileId} · ${connection.externalModelId}`;
  const { wire } = connection;
  if (wire.status === "unsupported") return `${where}: unsupported (${wire.protocol})`;
  if (wire.status === "unknown") {
    const apis = Object.keys(connection.profile.apis).join(", ") || "none";
    return `${where}: wire unknown — tries ${apis} in turn`;
  }
  const base = requestBaseUrl(connection, wire.api);
  const url = base ? wireRequestUrl(base, wire.api, connection.externalModelId) : "no base URL";
  const status = (value: string | { status: string }) =>
    typeof value === "string" ? value : value.status;
  const parts = [`${wire.api} ${url}`, `limit ${status(wire.tokenParam)}`];
  const reasoning = wire.reasoning;
  if (reasoning.status === "supported") {
    const effort = reasoning.effort;
    parts.push(
      "path" in effort
        ? `effort ${effort.path} [${Object.keys(effort.values).join(",")}]`
        : `effort ${effort.status}`
    );
    if (reasoning.mode.status === "supported") {
      parts.push(`modes ${Object.keys(reasoning.mode.values).join(",")}`);
    }
  } else {
    parts.push(`reasoning ${reasoning.status}`);
  }
  if (wire.speed.status === "supported")
    parts.push(`speeds ${Object.keys(wire.speed.values).join(",")}`);
  return `${where}: ${parts.join(" · ")}`;
}

/** Pin a transport's endpoint to `url`, delegating everything else to it. */
function withEndpoint(inner: ProviderTransport, url: string): ProviderTransport {
  return new Proxy(inner, {
    get(target, property, receiver) {
      if (property === "getEndpoint") return () => url;
      const value = Reflect.get(target, property, receiver);
      return typeof value === "function" ? value.bind(target) : value;
    },
  });
}

function adapterFor(
  api: WireApi,
  modelName: string,
  providerName: string,
  definitionName: string,
  vendor: string | undefined
): BaseAPIFormat {
  switch (api) {
    case "chat-completions":
      return definitionName === "openrouter"
        ? new OpenRouterAPIFormat(modelName, { vendor: vendor ?? "" })
        : new OpenAIAPIFormat(modelName);
    case "responses":
      return new CodexAPIFormat(modelName, undefined, {
        codexExtras: definitionName === "openai-codex",
      });
    case "anthropic-messages":
      return new AnthropicAPIFormat(modelName, providerName);
    case "gemini":
      return new GeminiAPIFormat(modelName);
  }
}

/**
 * The provider's own transport for `api`: who signs, which identity headers,
 * which extra fields. Its endpoint is replaced by the registry URL, except
 * Codex, whose host is decided by the credential that signs (OAuth →
 * chatgpt.com, API key → api.openai.com; `routing.md`).
 */
function transportFor(
  definitionName: string,
  api: WireApi,
  ctx: ProfileContext,
  url: string
): ProviderTransport {
  if (definitionName === "openai-codex") {
    return new OpenAICodexTransport(ctx.provider, ctx.modelName, ctx.apiKey);
  }
  // Muse Code signs with a minted key, and only on Responses (the API its
  // subscription billing was verified on); `buildWireHandler` never builds it
  // on another API.
  if (definitionName === "meta-muse-code" && api === "responses") {
    return withEndpoint(new MuseCodeTransport(ctx.provider, ctx.modelName, ""), url);
  }
  let inner: ProviderTransport;
  if (api === "anthropic-messages") {
    const provider: RemoteProvider = OPENCODE.has(definitionName)
      ? { ...ctx.provider, authScheme: "x-api-key" }
      : ctx.provider;
    inner = OPENCODE.has(definitionName)
      ? new OpenCodeZenMessagesTransport(provider, ctx.apiKey)
      : new AnthropicProviderTransport(provider, ctx.apiKey);
  } else if (api === "gemini" && definitionName === "google") {
    inner = new GeminiProviderTransport(ctx.provider, ctx.modelName, ctx.apiKey);
  } else if (OPENCODE.has(definitionName)) {
    inner = new OpenCodeZenTransport(ctx.provider, ctx.modelName, ctx.apiKey);
  } else if (definitionName === "openrouter") {
    inner = new OpenRouterProviderTransport(ctx.apiKey, ctx.modelName);
  } else if (definitionName === "poe") {
    inner = new PoeProvider();
  } else {
    inner = new OpenAIProviderTransport(ctx.provider, ctx.modelName, ctx.apiKey);
  }
  return withEndpoint(inner, url);
}

/**
 * A handler that sends nothing and answers every request with `message`.
 *
 * Returned for a connection that must not be called, instead of `null`: a null
 * handler falls through to the OpenRouter fallback, which is exactly the
 * silent substitution the wire reader exists to end. 400 because the request,
 * not the network, is what cannot be served.
 */
export class RefusingHandler implements ModelHandler {
  constructor(private readonly message: string) {}

  async handle(): Promise<Response> {
    log(`[Wire] refused: ${this.message}`);
    return new Response(
      JSON.stringify(wrapAnthropicError(400, `claudish: ${this.message}`, "invalid_request_error")),
      { status: 400, headers: { "Content-Type": "application/json" } }
    );
  }

  async shutdown(): Promise<void> {}
}

/**
 * How long building a catalog handler waits for a refresh that writes the
 * route registry. A full refresh (model pages, plans, registry) measured 9.3s
 * on 2026-10-12; the old 5s wait refused the first requests after an upgrade.
 */
const CATALOG_WAIT_MS = 30_000;

/**
 * The handler for a catalog provider while no route registry is readable:
 * each request waits for the refresh again and builds the real handler once
 * it can, answering with the refusal only for the requests that still find
 * no catalog. Never a cached refusal.
 */
export class CatalogPendingHandler implements ModelHandler {
  private built?: ModelHandler;

  constructor(
    private readonly ctx: ProfileContext,
    private readonly definitionName: string,
    private readonly message: string
  ) {}

  async handle(c: Context, payload: any): Promise<Response> {
    if (!this.built) {
      const outcome = await buildWireHandler(this.ctx, this.definitionName);
      if (outcome.kind === "handler" && !(outcome.handler instanceof CatalogPendingHandler)) {
        this.built = outcome.handler;
      } else {
        return new RefusingHandler(
          outcome.kind === "refused" ? outcome.message : this.message
        ).handle();
      }
    }
    return this.built.handle(c, payload);
  }

  async shutdown(): Promise<void> {
    await this.built?.shutdown();
  }
}

export type WireHandlerOutcome =
  /** Built from the wire, or a {@link TryInTurnHandler} when the wire is unknown. */
  | { kind: "handler"; handler: ModelHandler }
  /** Not a wire-routed provider: the caller builds its handler as before. */
  | { kind: "not-wire-routed" }
  /** The request must not be sent; `message` says why. */
  | { kind: "refused"; message: string };

export async function buildWireHandler(
  ctx: ProfileContext,
  definitionName: string
): Promise<WireHandlerOutcome> {
  if (NOT_WIRE_ROUTED.has(definitionName)) return { kind: "not-wire-routed" };

  let resolution = resolveConnection(definitionName, ctx.modelName, ctx.catalogCachePath);
  if (resolution.ok === false && resolution.reason === "not-catalog-routed") {
    return { kind: "not-wire-routed" };
  }
  if (
    resolution.ok === false &&
    (resolution.reason === "no-catalog" || resolution.reason === "no-registry") &&
    // A cache path is the test seam: a fixture is never refreshed from the network.
    !ctx.catalogCachePath
  ) {
    await ensureRouteRegistryReady(CATALOG_WAIT_MS);
    resolution = resolveConnection(definitionName, ctx.modelName, ctx.catalogCachePath);
  }
  if (resolution.ok === false) {
    if (resolution.reason === "no-catalog" || resolution.reason === "no-registry") {
      const message =
        `the cloud models catalog (with its route registry) is not available, so ${definitionName}@${ctx.modelName} ` +
        "cannot be called: claudish sends catalog providers nothing it was not told. Run `claudish --models-refresh`; local models still work.";
      // A fixture says what it says. In production the refresh may simply
      // not have finished: the proxy caches handlers per model, so a refusal
      // returned here would outlive the refresh for the whole session.
      if (ctx.catalogCachePath) return { kind: "refused", message };
      return { kind: "handler", handler: new CatalogPendingHandler(ctx, definitionName, message) };
    }
    // The catalog does not publish this model on this provider (a model newer
    // than the generation, or one only the account knows). The route profile
    // still says which APIs the host serves: try them in turn.
    const profile = resolveRouteProfile(definitionName, ctx.catalogCachePath);
    if (!profile) return { kind: "not-wire-routed" };
    const unpublished: ResolvedConnection = {
      provider: definitionName,
      modelId: ctx.modelName,
      route: profile.route,
      externalModelId: ctx.modelName,
      wire: { status: "unknown", evidence: [] },
      profile: profile.profile,
      generationId: profile.generationId,
    };
    return tryInTurn(ctx, definitionName, unpublished, "not published for this provider");
  }

  const connection = resolution.connection;
  const { wire } = connection;
  if (wire.status === "unsupported") {
    return {
      kind: "refused",
      message:
        `${connection.route.routeId}/${connection.route.routeProfileId} · ${connection.externalModelId} speaks ` +
        `${wire.protocol}, which claudish does not implement`,
    };
  }
  if (wire.status === "unknown") return tryInTurn(ctx, definitionName, connection, "wire unknown");
  if (definitionName === "meta-muse-code" && wire.api !== "responses") {
    return tryInTurn(
      ctx,
      definitionName,
      connection,
      `Muse Code is billed on responses, not ${wire.api}`
    );
  }

  const handler = buildKnownWireHandler(ctx, definitionName, connection, wire);
  return handler
    ? { kind: "handler", handler }
    : tryInTurn(ctx, definitionName, connection, `no base URL for ${wire.api}`);
}

function tryInTurn(
  ctx: ProfileContext,
  definitionName: string,
  connection: ResolvedConnection,
  why: string
): WireHandlerOutcome {
  const label = `${connection.route.routeId}/${connection.route.routeProfileId} · ${connection.externalModelId}`;
  // Muse Code: Responses only, whatever else its host serves (see transportFor).
  const apis = (Object.keys(connection.profile.apis) as WireApi[]).filter(
    (api) => definitionName !== "meta-muse-code" || api === "responses"
  );
  if (apis.length === 0) {
    return { kind: "refused", message: `${label}: ${why}, and its route profile publishes no API` };
  }
  log(`[Wire] ${label}: ${why} — trying ${apis.join(", ")} in turn (a catalog gap)`);
  const key = `${connection.generationId}|${label}`;
  return {
    kind: "handler",
    handler: new TryInTurnHandler(key, label, apis, (api) => {
      const wire = apiOnlyWire(api);
      return buildKnownWireHandler(ctx, definitionName, { ...connection, wire }, wire);
    }),
  };
}

export function buildKnownWireHandler(
  ctx: ProfileContext,
  definitionName: string,
  connection: ResolvedConnection,
  wire: KnownWire
): ModelHandler | null {
  const registryBase = requestBaseUrl(connection, wire.api);
  if (!registryBase) return null;
  const definition = getProviderByName(definitionName);
  // Muse keys stay on Meta, regardless of registry or user base URLs.
  const { baseUrl, overridden } =
    definitionName === "meta-muse-code"
      ? { baseUrl: registryBase, overridden: false }
      : effectiveBaseUrl(registryBase, definition?.baseUrl, ctx.provider.baseUrl);
  if (
    definitionName === "meta-muse-code" &&
    ctx.provider.baseUrl &&
    ctx.provider.baseUrl !== definition?.baseUrl
  ) {
    log(`[Wire] meta-muse-code: user base URL ignored → ${baseUrl}`);
  }
  const url = wireRequestUrl(baseUrl, wire.api, connection.externalModelId);
  if (overridden) log(`[Wire] ${definitionName}: base URL overridden by user config → ${baseUrl}`);

  const transport = transportFor(definitionName, wire.api, ctx, url);
  const adapter = adapterFor(
    wire.api,
    ctx.modelName,
    ctx.provider.name,
    definitionName,
    connection.vendor
  );
  const handler = new ComposedHandler(transport, ctx.targetModel, ctx.modelName, ctx.port, {
    adapter,
    ...(wire.api === "chat-completions" || wire.api === "responses"
      ? { tokenStrategy: "delta-aware" as const }
      : {}),
    ...ctx.sharedOpts,
    connection,
  });
  log(
    `[Wire] ${definitionName}@${ctx.modelName} → ${connection.route.routeId}/${connection.route.routeProfileId} · ` +
      `${connection.externalModelId}: ${wire.api} ${definitionName === "openai-codex" ? "(credential-decided host)" : url} ` +
      `[generation ${connection.generationId}]`
  );
  return handler;
}