Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

7.5 KB
Raw Blame
/**
 * Custom model providers.
 *
 * An org admin can register additional model providers that speak a wire
 * protocol we already run — OpenAI Chat Completions, OpenAI Responses,
 * or Anthropic Messages — by giving a base URL, an API key, and the model
 * ids to expose. Registered models resolve like built-ins (the pi
 * harness reaches them through the same request path), surface in the
 * catalog, and are gated to harnesses that route through pi-ai.
 *
 * Secrets never live here: this module holds the runtime registry
 * (everything except the key). Keys stay in the encrypted store and are
 * resolved per-call by wiring alongside the built-in provider keys.
 */

import { parseProviderBaseUrl, PROVIDER_IDS } from "./provider-endpoints.ts";

export const CUSTOM_PROVIDER_PROTOCOLS = ["openai", "openai-responses", "anthropic"] as const;
export type CustomProviderProtocol = (typeof CUSTOM_PROVIDER_PROTOCOLS)[number];

interface CustomModelSpec {
  id: string;
  name?: string;
  reasoning?: boolean;
  contextWindow?: number;
  maxTokens?: number;
  /** USD per million input tokens. Defaults to 0 (unknown / not metered). */
  input?: number;
  /** USD per million output tokens. Defaults to 0. */
  output?: number;
}

export interface CustomProviderSpec {
  /** Slug: lowercase, digits, hyphens; also the model's `provider` value. */
  id: string;
  name: string;
  protocol: CustomProviderProtocol;
  baseUrl: string;
  models: CustomModelSpec[];
}

const SLUG_RE = /^[a-z][a-z0-9-]{1,31}$/;
const RESERVED = new Set<string>(PROVIDER_IDS);

export function validateCustomProviderSpec(spec: CustomProviderSpec): void {
  if (!SLUG_RE.test(spec.id)) {
    throw new Error(`provider id must match ${SLUG_RE} (lowercase slug), got "${spec.id}"`);
  }
  if (RESERVED.has(spec.id)) throw new Error(`provider id "${spec.id}" is reserved`);
  if (!spec.name.trim()) throw new Error("provider name is required");
  if (spec.name.length > 100) throw new Error("provider name must be 100 chars or fewer");
  if (!CUSTOM_PROVIDER_PROTOCOLS.includes(spec.protocol)) {
    throw new Error(`protocol must be one of ${CUSTOM_PROVIDER_PROTOCOLS.join(", ")}`);
  }
  parseProviderBaseUrl(`custom provider ${spec.id} baseUrl`, spec.baseUrl);
  if (!Array.isArray(spec.models) || spec.models.length === 0) {
    throw new Error("at least one model is required");
  }
  if (spec.models.length > 200) throw new Error("at most 200 models per provider");
  const seen = new Set<string>();
  for (const m of spec.models) {
    if (!m.id?.trim() || m.id.length > 200) throw new Error("every model needs an id (<=200 chars)");
    if (m.name !== undefined && (typeof m.name !== "string" || m.name.length > 200))
      throw new Error(`model "${m.id}": name must be a string of 200 chars or fewer`);
    if (m.reasoning !== undefined && typeof m.reasoning !== "boolean")
      throw new Error(`model "${m.id}": reasoning must be a boolean`);
    if (seen.has(m.id)) throw new Error(`duplicate model id "${m.id}"`);
    seen.add(m.id);
    for (const [field, v] of [
      ["contextWindow", m.contextWindow],
      ["maxTokens", m.maxTokens],
    ] as const) {
      if (v !== undefined && (!Number.isSafeInteger(v) || v <= 0)) {
        throw new Error(`model "${m.id}": ${field} must be a positive safe integer`);
      }
    }
    for (const [field, v] of [
      ["input", m.input],
      ["output", m.output],
    ] as const) {
      if (v !== undefined && (typeof v !== "number" || !Number.isFinite(v) || v < 0)) {
        throw new Error(`model "${m.id}": ${field} must be a non-negative number`);
      }
    }
  }
}

/**
 * The wire-level shape pi-ai expects. We construct these without
 * importing pi-ai so this module stays dependency-free; pi-models casts
 * at its boundary, the same way it treats getBuiltinModel.
 */
export interface CustomRuntimeModel {
  id: string;
  upstreamId: string;
  name: string;
  provider: string;
  api: "openai-completions" | "openai-responses" | "anthropic-messages";
  baseUrl: string;
  reasoning: boolean;
  input: ("text" | "image")[];
  cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
  contextWindow: number;
  maxTokens: number;
}

const CUSTOM_MODEL_PREFIX = "custom/";
const DEFAULT_CONTEXT_WINDOW = 128_000;
const DEFAULT_MAX_TOKENS = 8_192;

function customProviderApi(protocol: CustomProviderProtocol): CustomRuntimeModel["api"] {
  if (protocol === "anthropic") return "anthropic-messages";
  if (protocol === "openai-responses") return "openai-responses";
  return "openai-completions";
}

function toRuntimeModel(provider: CustomProviderSpec, m: CustomModelSpec): CustomRuntimeModel {
  return {
    id: `${CUSTOM_MODEL_PREFIX}${provider.id}/${m.id}`,
    upstreamId: m.id,
    name: m.name?.trim() || m.id,
    provider: provider.id,
    api: customProviderApi(provider.protocol),
    baseUrl: provider.baseUrl,
    reasoning: m.reasoning ?? false,
    input: ["text"],
    cost: { input: m.input ?? 0, output: m.output ?? 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: m.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
    maxTokens: m.maxTokens ?? DEFAULT_MAX_TOKENS,
  };
}

let registry = new Map<string, CustomRuntimeModel>();
let providers: CustomProviderSpec[] = [];
let version = 0;

/**
 * Called by wiring at boot and again after every admin write, with the
 * full current set of enabled providers. Last write wins; built-in model
 * ids shadow custom ones at resolution, so a collision can't hijack a
 * built-in.
 */
export function setCustomProviders(specs: CustomProviderSpec[]): void {
  const snapshot = JSON.stringify(specs);
  if (snapshot === JSON.stringify(providers)) return;
  const next = new Map<string, CustomRuntimeModel>();
  for (const spec of specs) {
    for (const m of spec.models) {
      const model = toRuntimeModel(spec, m);
      next.set(model.id, model);
    }
  }
  registry = next;
  providers = specs.map((s) => ({ ...s, models: [...s.models] }));
  version += 1;
}

/** Bumps on every registry change — lets callers cache derived artifacts. */
export function customProvidersVersion(): number {
  return version;
}

export function hasCustomModelPrefix(id: string): boolean {
  return id.startsWith(CUSTOM_MODEL_PREFIX);
}

export function resolveCustomModel(id: string): CustomRuntimeModel | undefined {
  return registry.get(id);
}

export function isCustomModelId(id: string): boolean {
  return registry.has(id);
}

export function customModelCatalog(): Array<{ id: string; name: string; provider: string }> {
  return [...registry.values()].map((m) => ({ id: m.id, name: m.name, provider: m.provider }));
}

/**
 * The models.json fragment pi-coding-agent understands. Materialized to a
 * temp file whenever the pi harness builds a model runtime, so the
 * runtime's own provider registry knows each custom provider natively —
 * a runtime API key alone is not enough (availability checks only cover
 * providers the ModelsStore knows).
 */
export function customModelsJson(): { providers: Record<string, unknown> } | undefined {
  if (providers.length === 0) return undefined;
  return {
    providers: Object.fromEntries(
      providers.map((spec) => [
        spec.id,
        {
          name: spec.name,
          baseUrl: spec.baseUrl,
          api: customProviderApi(spec.protocol),
          models: [...registry.values()]
            .filter((m) => m.provider === spec.id)
            .map(({ id, name, reasoning, contextWindow, maxTokens, cost }) => ({
              id,
              name,
              reasoning,
              contextWindow,
              maxTokens,
              cost,
            })),
        },
      ]),
    ),
  };
}