Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

3.7 KB
Raw Blame
/**
 * Endpoint model listing — the thin core wrapper over `AutoLLMClient.listModels()`.
 *
 * Exists so hosts (the server's models routes) can enumerate what an endpoint serves
 * without depending on AgentHub directly: core mediates the AgentHub boundary, AgentHub
 * owns the client and the per-protocol `/models` call. Routed through a **generic protocol
 * client type** (`openai-responses` / `ant-messages` / `openai-chat`), the listing is the
 * endpoint's whole catalog; routed through a vendor-pinned type, AgentHub filters the ids
 * down to that client's own models, and a client with no models endpoint rejects with its
 * `UnsupportedOperationError` (recognizable by `err.name`).
 *
 * Credential semantics mirror the connectivity test: an omitted `apiKey` falls back to the
 * protocol's environment variable (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`) **only when the
 * base URL is that vendor's own endpoint** (see endpointEnvApiKey) — the wrapped SDK would
 * otherwise read the variable itself and send the
 * user's vendor key to whatever endpoint was typed, so with no usable key the listing is
 * refused before a client exists. Other failures surface as the SDK's own errors — callers
 * collapse errors into their outcome shape, nothing is caught here.
 */
import { AutoLLMClient } from "@prismshadow/agenthub";
import {
  ModelCredentialError,
  endpointEnvApiKey,
  modelEnvFallback,
} from "../state/model-catalog.js";

/** One endpoint listing request: which protocol to speak, and the credential/URL to speak it with. */
export interface ListEndpointModelsOptions {
  /** AgentHub client type to route through (the add-group flow passes a detected generic protocol). */
  clientType: string;
  /** Plaintext API key; omitted = the environment fallback for the protocol, where the endpoint allows one. */
  apiKey?: string;
  /** Endpoint base URL; omitted = the vendor default of the routed client. */
  baseUrl?: string;
  /** Environment the fallback reads; defaults to `process.env` (injectable for tests). */
  env?: Readonly<Record<string, string | undefined>>;
}

/**
 * Lists the model ids the endpoint serves, in the order the endpoint returned them.
 * Throws whatever AgentHub or the wrapped SDK throws (unsupported operation, auth,
 * network), or a ModelCredentialError when there is no key and the endpoint may not use
 * the environment's; bounding the call in time is the caller's concern.
 */
export async function listEndpointModels(options: ListEndpointModelsOptions): Promise<string[]> {
  const apiKey =
    options.apiKey || endpointEnvApiKey(options.clientType, options.baseUrl, options.env);
  if (apiKey === undefined) {
    // Two different situations, two messages: the vendor's own endpoint with its variable
    // simply unset, and an endpoint the environment is not lent to at all.
    const allowed = modelEnvFallback({
      provider: "custom",
      modelId: "",
      clientType: options.clientType,
      baseUrl: options.baseUrl,
    });
    throw new ModelCredentialError(
      allowed !== undefined
        ? `No API key for ${options.baseUrl ?? "the endpoint"}: ${allowed.envKey} is not set in the server environment. Enter the API key, or set the variable.`
        : `No API key for ${options.baseUrl ?? "the endpoint"}. The environment lends a key only to a vendor's own endpoint: enter the endpoint's API key.`,
    );
  }
  const client = new AutoLLMClient({
    // AutoLLMClient routes by clientType when given one; model is its fallback routing key
    // and must still be a string, so the client type doubles as it.
    model: options.clientType,
    clientType: options.clientType,
    apiKey,
    ...(options.baseUrl ? { baseUrl: options.baseUrl } : {}),
  });
  return client.listModels();
}