Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.8 KB
Raw Blame
/**
 * [CX-P0.5] Keyless capability probe — config-plane only, no network.
 *
 * Bootstrap must work with ZERO API keys (the harness agent is the
 * subsidized LLM; search degrades to BM25 keyword; facts come from
 * agent-authored `## Facts` fences and explicit write ops). This module
 * answers "what can this install actually do?" from configuration alone:
 *
 *   - embeddings  → can we compute vectors? (drives semantic vs keyword search)
 *   - extraction  → can we call a chat model? (drives auto facts/enrichment
 *                   and the corpus-ingest pass of the maintenance sweep)
 *
 * Detection mirrors the provider picker (src/commands/init-provider-picker.ts
 * `envReady`) and the gateway's availability predicate
 * (src/core/ai/gateway.ts `isAvailable` / `diagnoseEmbedding`): a touchpoint
 * is available when its model's recipe exists, declares the touchpoint, and
 * every `auth_env.required` var is present in the merged env. The merged env
 * folds file-plane config keys exactly the way
 * `src/core/ai/build-gateway-config.ts` does (that module is the canonical
 * mapping — update BOTH if a new provider key seam is added), then overlays
 * real process-env values (env wins, empty strings dropped, #1249).
 *
 * Deliberately NOT routed through the gateway module: the gateway's
 * `_config` is process-global mutable state set at engine connect, and this
 * probe must be callable from `bootstrap verify` / the runbook / the sweep
 * without booting providers. Config + env injection keeps tests hermetic.
 */

import { loadConfig, type GBrainConfig } from './config.ts';
import { RECIPES } from './ai/recipes/index.ts';
import type { Recipe } from './ai/types.ts';
import { DEFAULT_EMBEDDING_MODEL } from './ai/defaults.ts';

// Extraction probes the SAME effective-model resolution the gateway's
// reconfigure fallback uses (resolveEffectiveChatModel) — runtime routing and
// this report cannot diverge by construction. Known accepted limitation:
// DB-plane overrides (`models.default`, `facts.extraction_model`) are
// invisible to this engine-less probe; the runtime gate in facts/extract.ts
// and the engine-aware pre-enqueue gate in facts/backstop.ts are the
// backstops.
import { resolveEffectiveChatModel } from './model-config.ts';
import { mergedProviderEnv } from './ai/provider-env.ts';

export interface TouchpointCapability {
  available: boolean;
  /** Provider (recipe id) serving the touchpoint when available. */
  provider?: string;
}

export interface CapabilityReport {
  embeddings: TouchpointCapability;
  extraction: TouchpointCapability;
  /** 'semantic' when embeddings are available; BM25 'keyword-only' otherwise. */
  search: 'semantic' | 'keyword-only';
  /** 'keyless' when NO paid touchpoint is configured — the CX-P0.5 posture. */
  mode: 'keyed' | 'keyless';
}

export interface DetectCapabilitiesOpts {
  /**
   * File-plane config. `undefined` = load via loadConfig(); explicit `null`
   * = "no config file" (fresh install). Injected by tests.
   */
  config?: GBrainConfig | null;
  /** Env to probe. Defaults to process.env. Injected by tests. */
  env?: Record<string, string | undefined>;
}

// The provider-key/env fold lives in src/core/ai/provider-env.ts
// (mergedProviderEnv) — one canonical mapping shared with buildGatewayConfig
// and the key-aware model resolution. This probe additionally sees the Azure
// endpoint/deployment fields the old local copy omitted.

/** `envReady` twin (src/commands/providers.ts:52) — auth-env readiness only. */
function recipeReady(recipe: Recipe, env: Record<string, string>): boolean {
  const required = recipe.auth_env?.required ?? [];
  if (required.length === 0) return true; // e.g. local Ollama
  return required.every(k => !!env[k]);
}

function probeTouchpoint(
  modelStr: string | undefined,
  touchpoint: 'embedding' | 'chat',
  env: Record<string, string>,
): TouchpointCapability {
  if (!modelStr) return { available: false };
  const providerId = modelStr.includes(':') ? modelStr.slice(0, modelStr.indexOf(':')) : modelStr;
  const recipe = RECIPES.get(providerId);
  if (!recipe) return { available: false };
  const tp = recipe.touchpoints[touchpoint];
  if (!tp) return { available: false };
  if (!recipeReady(recipe, env)) return { available: false };
  return { available: true, provider: recipe.id };
}

/**
 * Detect what this install can do, from config + env alone. Never touches
 * the network, the DB, or the gateway's process-global state.
 */
export function detectCapabilities(opts: DetectCapabilitiesOpts = {}): CapabilityReport {
  let cfg: GBrainConfig | null;
  if (opts.config !== undefined) {
    cfg = opts.config;
  } else {
    try {
      cfg = loadConfig();
    } catch {
      cfg = null; // unreadable config = fresh-install posture, not a crash
    }
  }
  const rawEnv = opts.env ?? process.env;
  const env = mergedProviderEnv(cfg, rawEnv);

  const embeddings = cfg?.embedding_disabled || (cfg && !cfg.embedding_model?.trim())
    ? { available: false }
    : probeTouchpoint(
    cfg?.embedding_model ?? DEFAULT_EMBEDDING_MODEL,
    'embedding',
    env,
  );
  // Probe the model extraction will ACTUALLY use: GBRAIN_MODEL > servable
  // file pin > key-aware tier default — the same shared resolution the
  // gateway's reconfigure fallback applies (so a stale unservable pin
  // degrades identically here and at runtime).
  const extraction = probeTouchpoint(
    resolveEffectiveChatModel(cfg, rawEnv).model,
    'chat',
    env,
  );

  return {
    embeddings,
    extraction,
    search: embeddings.available ? 'semantic' : 'keyword-only',
    mode: embeddings.available || extraction.available ? 'keyed' : 'keyless',
  };
}

/**
 * Human-readable capability report — used by `bootstrap verify` and the
 * runbook (CX-P0.5: verify prints an honest capability report). One line
 * per touchpoint plus the keyless upsell when applicable.
 */
export function renderCapabilityReport(caps: CapabilityReport): string {
  const lines: string[] = [];
  lines.push(`gbrain capabilities: ${caps.mode} mode`);
  lines.push(
    caps.embeddings.available
      ? `  embeddings: available via ${caps.embeddings.provider} — semantic (hybrid vector + keyword) search`
      : '  embeddings: not configured — search runs keyword-only (BM25)',
  );
  lines.push(
    caps.extraction.available
      ? `  extraction: available via ${caps.extraction.provider} — automatic facts/enrichment + corpus ingest`
      : '  extraction: not configured — memory comes from agent-authored ## Facts fences and write ops',
  );
  if (caps.mode === 'keyless') {
    lines.push(
      'keyless mode: keyword search, agent-authored memory; one optional key upgrades ' +
      'capabilities — OpenAI: semantic search + auto-extraction; Voyage: semantic search; ' +
      'Anthropic: auto-extraction (see `gbrain providers list` for env-ready options).',
    );
  }
  return lines.join('\n');
}