Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.4 KB
Raw Blame
import { resolveRecipe } from './model-resolver.ts';
import type { AIGatewayConfig } from './types.ts';

/** Which doctor failure triggered the sweep. Shapes wording and control-probe use. */
type Trigger = 'auth' | 'model_not_found';

/**
 * Canonical version prefixes probed against an openai-compatible proxy's
 * `/models` endpoint. `/v1` is the OpenAI default; `/v1beta` covers Gemini-shaped
 * routes. Each is tried off the base URL's version-root, so they serve both the
 * "append to a bare base" and "switch a wrong version" cases. Extend here, not at
 * a call site.
 */
const V1_SUFFIX_CANDIDATES = ['/v1', '/v1beta'] as const;

/**
 * The base URL with a trailing `/vN` version segment (optional channel suffix
 * like `/v1beta`, optional trailing slash) removed: `http://h/v4` -> `http://h`;
 * a bare `http://h` is returned unchanged. Canonical candidates are probed off
 * this root so a wrong configured version becomes a swap, not an append.
 */
export function versionRoot(baseURL: string): string {
  return baseURL.replace(/\/+$/, '').replace(/\/v\d+[a-z]*$/i, '');
}

/**
 * GET `url` with the given headers; return the HTTP status, or `null` on any
 * transport error (DNS, connection refused, timeout). Never throws. Uses
 * `AbortSignal.timeout` to match the gateway's fetch-timeout idiom, and
 * `redirect: 'manual'` so a 3xx is never followed: the classifier only reads
 * {200,401,403,404}, so following a redirect buys nothing and could forward the
 * bearer to another origin.
 */
async function fetchProbeStatus(
  url: string,
  headers: Record<string, string>,
  fetchImpl: typeof fetch,
  timeoutMs: number,
): Promise<number | null> {
  try {
    const res = await fetchImpl(url, {
      method: 'GET',
      headers,
      redirect: 'manual',
      signal: AbortSignal.timeout(timeoutMs),
    });
    return res.status;
  } catch {
    return null;
  }
}

/**
 * The diagnosis a `/models` probe sweep supports. Most kinds are auth-only;
 * `model-name` is model_not_found-only; `use-verified` carries its trigger
 * because its wording differs. `undefined` (returned separately) means the
 * statuses were inconclusive.
 */
type BaseUrlVerdict =
  | { kind: 'use-verified'; recommend: string; trigger: Trigger } // an alternate's /models 200s: the route is there
  | { kind: 'switch-or-key'; recommend: string }                 // auth: configured unauthorized + alt 200 that is public/unconfirmed
  | { kind: 'use-and-key'; recommend: string; status: number }   // auth: configured 404, alt 401/403: wrong version AND creds rejected
  | { kind: 'key-or-model' }                                     // auth: configured 200: URL reaches a working endpoint
  | { kind: 'key-only'; status: number }                         // auth: configured 401/403, no other version serves /models
  | { kind: 'wrong-endpoint' }                                   // auth: no /models at the configured path or any probed version
  | { kind: 'model-name' };                                      // model_not_found: configured 200: URL correct, the model id is wrong

/**
 * Probe `/models` at the configured base URL AND each canonical version off its
 * root, with the SAME bearer, in parallel, and classify what the status codes
 * prove. A `200` means that path serves a models list for the request we sent;
 * a `404` means the path is absent; a `401`/`403` means the path exists but
 * rejected the credentials. Other statuses (5xx, 429) and transport errors
 * prove nothing.
 *
 * The `trigger` splits behavior: on `auth` the full verdict set runs (including
 * a control-probe that confirms the key when an alternate authenticates); on
 * `model_not_found` only a real 200 speaks (append/switch, or "URL correct,
 * check the model name"), because the key is not in question and a redirect to
 * a check-the-key message would misdirect.
 */
async function classifyBaseUrlProbe(
  baseURL: string,
  headers: Record<string, string>,
  candidates: readonly string[],
  fetchImpl: typeof fetch,
  timeoutMs: number,
  trigger: Trigger,
): Promise<BaseUrlVerdict | undefined> {
  const base = baseURL.replace(/\/+$/, '');
  const root = versionRoot(base);

  // Probe set: the configured URL as-is, plus each canonical version off the
  // root. Dedup so an already-`/v1` base does not probe `/v1` twice.
  const targets: Array<{ suffix: string; configured: boolean }> = [];
  const seen = new Set<string>();
  const add = (suffix: string, configured: boolean) => {
    const url = `${root}${suffix}/models`;
    if (!seen.has(url)) {
      seen.add(url);
      targets.push({ suffix, configured });
    }
  };
  add(base.slice(root.length), true); // configured: '' when bare, else '/vX'
  for (const cand of candidates) add(cand, false);

  const statuses = await Promise.all(
    targets.map(t => fetchProbeStatus(`${root}${t.suffix}/models`, headers, fetchImpl, timeoutMs)),
  );
  const items = targets.map((t, i) => ({ ...t, status: statuses[i] }));
  const authReject = (s: number | null) => s === 401 || s === 403;
  const configured = items.find(t => t.configured)!;
  const alternates = items.filter(t => !t.configured);
  const working = alternates.find(t => t.status === 200);

  // model_not_found: the key is not in question, so speak only on positive URL
  // evidence (a real 200) and stay silent on everything else.
  if (trigger === 'model_not_found') {
    if (configured.status === 200) return { kind: 'model-name' };
    if (working) return { kind: 'use-verified', recommend: working.suffix, trigger };
    return undefined;
  }

  // auth trigger.
  // Configured /models serves a list: the base URL reaches a working route, so
  // the failure is credentials or model access, not the URL shape.
  if (configured.status === 200) return { kind: 'key-or-model' };

  if (working) {
    // A version answers 200 with the key. Disambiguate "the key is valid there"
    // (confident switch) from "that /models is public, key unproven" (both
    // signals) with one unauthenticated control-probe.
    const { Authorization: _drop, ...noAuthHeaders } = headers;
    const noAuth = await fetchProbeStatus(`${root}${working.suffix}/models`, noAuthHeaders, fetchImpl, timeoutMs);
    if (authReject(noAuth)) {
      // /models requires auth AND accepted the key -> the key is valid there.
      return { kind: 'use-verified', recommend: working.suffix, trigger };
    }
    // public or unconfirmed -> name both signals.
    return { kind: 'switch-or-key', recommend: working.suffix };
  }

  // Configured path is absent (404).
  if (configured.status === 404) {
    const rejected = alternates.find(t => authReject(t.status));
    if (rejected) return { kind: 'use-and-key', recommend: rejected.suffix, status: rejected.status! };
    if (alternates.every(t => t.status === 404)) return { kind: 'wrong-endpoint' };
  }

  // Configured path exists and rejects the credentials, and no other version
  // serves /models: the URL shape is fine, the problem is the key/permissions.
  if (authReject(configured.status) && alternates.every(t => t.status === 404 || t.status === null)) {
    return { kind: 'key-only', status: configured.status! };
  }

  return undefined; // inconclusive: 401-everywhere, 5xx/429, or transport errors
}

/** Render a verdict into the operator-facing `fix:` line. */
function verdictHint(verdict: BaseUrlVerdict, baseURL: string): string {
  const base = baseURL.replace(/\/+$/, '');
  const root = versionRoot(base);
  const from = base.slice(root.length); // '' when the base is bare, else '/vX'
  const move = (recommend: string) =>
    from ? `switch ${from} to ${recommend} (base URL ${root}${recommend})` : `append ${recommend} (base URL ${root}${recommend})`;
  switch (verdict.kind) {
    case 'use-verified': {
      const target = `${root}${verdict.recommend}`;
      if (verdict.trigger === 'model_not_found') {
        return `${target}/models responds 200 while ${base}/models does not, so the openai-compatible route is at ` +
          `${verdict.recommend} — ${move(verdict.recommend)}. That explains the model-not-found (the request reached the wrong path).`;
      }
      return `The API key authenticates at ${target} (its /models requires auth and accepted the key), but the ` +
        `configured ${base} does not serve that route, so the base URL ${from ? 'has the wrong' : 'is missing its'} ` +
        `version prefix — ${move(verdict.recommend)}.`;
    }
    case 'switch-or-key':
      return `The request was unauthorized, so check the API key first. Separately, ${root}${verdict.recommend}/models ` +
        `responds 200 (possibly an unauthenticated route), so if the key is correct the base URL should carry ` +
        `${verdict.recommend} — ${move(verdict.recommend)}.`;
    case 'use-and-key':
      return `The openai-compatible route appears to be at ${root}${verdict.recommend} (its /models responds ` +
        `${verdict.status} while the configured ${base}/models returns 404), so ${move(verdict.recommend)}. That route ` +
        `also rejects the current credentials (${verdict.status}), so verify the API key or permissions too.`;
    case 'key-or-model':
      return `${base}/models responds 200 with the configured credentials, so the base URL reaches a working ` +
        `openai-compatible endpoint. The failure is the API key or the model's access, not the URL shape.`;
    case 'key-only':
      return `${base}/models responds ${verdict.status} (the endpoint exists and rejected the credentials) and no ` +
        `other common version prefix serves /models, so the base URL shape is not the problem. Check the API key or permissions.`;
    case 'wrong-endpoint':
      return `The request was unauthorized and no /models list answered at ${base} or the common version prefixes ` +
        `(all 404), so this is most likely a key or permissions problem — check the API key. Some providers do not serve ` +
        `a /models list; if you expected one, verify the base URL host and path.`;
    case 'model-name':
      return `${base}/models responds 200, so the base URL is correct. The model-not-found is most likely a wrong or ` +
        `unavailable model name — check the model id (and that your key or plan can access it).`;
  }
}

/**
 * The mutable probe result `maybeAttachVersionSuffixHint` reads and annotates.
 * The doctor's `ProbeResult` is structurally compatible; kept minimal here so
 * this module does not depend on the command layer.
 */
export interface HintTarget {
  status: string;
  fix?: string;
}

/**
 * Injected config/transport for tests + a per-run memo cache. Real callers pass
 * the cache (created once per doctor run) so several probe sites sharing a base
 * URL do not each re-run the sweep.
 */
export interface HintDeps {
  cfg?: AIGatewayConfig;
  fetchImpl?: typeof fetch;
  cache?: Map<string, string | undefined>;
}

/**
 * On an `auth` (401/403) or `model_not_found` (404) probe failure against an
 * openai-compatible proxy, probe `/models` at the configured base URL and each
 * canonical version and attach a targeted `fix:` line.
 *
 * The base URL and bearer resolve through the same `applyOpenAICompatConfig` /
 * `applyResolveAuth` / `authToHeaders` seams the live gateway uses (read from
 * the live merged config via the gateway's own `requireConfig`, not a config-file
 * re-read, which would miss the DB-plane `base_urls` merge), so the probe hits
 * the exact path production does, on the same host the operator already trusts
 * with the key. Native providers and Azure-templated recipes (bespoke
 * `resolveOpenAICompatConfig`) are skipped. Fail-open: any resolution or
 * transport error yields no hint and never breaks the probe.
 *
 * @internal exported for tests.
 */
export async function maybeAttachVersionSuffixHint(
  target: HintTarget,
  modelStr: string,
  touchpoint: 'embedding' | 'expansion' | 'chat' | 'reranker',
  deps: HintDeps = {},
): Promise<void> {
  const trigger: Trigger | undefined =
    target.status === 'auth' ? 'auth' : target.status === 'model_not_found' ? 'model_not_found' : undefined;
  if (!trigger) return;
  try {
    const { requireConfig, applyOpenAICompatConfig, applyResolveAuth, authToHeaders } = await import('./gateway.ts');
    // Reuse the gateway's own live-config accessor (the DB + file + env merge),
    // not a file re-read. requireConfig throws if the gateway is unconfigured;
    // that path can't happen once doctor is probing models, and the fail-open
    // catch below absorbs it either way.
    const cfg = deps.cfg ?? requireConfig();
    const { recipe } = resolveRecipe(modelStr);
    if (recipe.tier !== 'openai-compat') return; // native provider — no base-URL trap
    if (recipe.resolveOpenAICompatConfig) return; // Azure-templated, non-/vN shape
    const { baseURL } = applyOpenAICompatConfig(recipe, cfg);
    if (!baseURL || !baseURL.trim()) return;

    // Per-run memo: verdicts depend only on (trigger, base URL, recipe), so
    // several probe sites sharing a proxy reuse one sweep. Key is non-secret.
    const cacheKey = `${trigger}\n${baseURL}\n${recipe.id}`;
    if (deps.cache?.has(cacheKey)) {
      const cached = deps.cache.get(cacheKey);
      if (cached) target.fix = cached;
      return;
    }

    const headers = authToHeaders(applyResolveAuth(recipe, cfg, touchpoint));
    const verdict = await classifyBaseUrlProbe(
      baseURL,
      headers,
      V1_SUFFIX_CANDIDATES,
      deps.fetchImpl ?? globalThis.fetch,
      2000,
      trigger,
    );
    const fix = verdict ? verdictHint(verdict, baseURL) : undefined;
    deps.cache?.set(cacheKey, fix);
    if (fix) target.fix = fix;
  } catch {
    // fail open — no hint
  }
}