Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.1 KB
Raw Blame
import { createHash } from 'crypto';
import type { BrainHealth } from './types.ts';
import { canonicalLookup } from './model-pricing.ts';
import { lookupEmbeddingPrice, estimateCostFromChars } from './embedding-pricing.ts';
import { getRecipe } from './ai/recipes/index.ts';
import { parseModelId } from './ai/model-resolver.ts';
import { getGatewayAnthropicKeySnapshot } from './ai/anthropic-key.ts';

/**
 * v0.40.x: env-var name → file/DB config field, for hosted embedding providers
 * whose config-plane key is actually propagated to the AI gateway. Producers of
 * RecommendationContext (doctor + autopilot) use this to build a sync
 * `resolveKey` closure without re-parsing recipes.
 *
 * Only keys that `buildGatewayConfig` (src/core/ai/build-gateway-config.ts)
 * actually folds from config into the gateway env may appear here.
 *
 * VOYAGE_API_KEY → voyage_api_key was the same kind of gap (#2662) until
 * buildGatewayConfig started folding it — now safe to list here too.
 * GOOGLE_GENERATIVE_AI_API_KEY → google_api_key and DASHSCOPE_API_KEY →
 * dashscope_api_key joined for the same reason (#3500): both are folded by
 * buildGatewayConfig now, so a config-plane key is genuinely usable by the
 * gateway and counting it here is no longer a false positive.
 *
 * The historical DB-plane/file-plane split for these fields is closed
 * (#2119 read-side): `loadConfigWithEngine()` sparse-merges every
 * `DB_MERGED_PROVIDER_KEY_FIELDS` entry from the DB plane (env > file > DB)
 * before `buildGatewayConfig` folds the merged config into the gateway env,
 * so a key that reads "configured" via `engine.getConfig()` is genuinely
 * usable by the gateway on any path that runs the DB merge.
 */
export const HOSTED_EMBED_KEY_CONFIG: Record<string, string> = {
  OPENAI_API_KEY: 'openai_api_key',
  VOYAGE_API_KEY: 'voyage_api_key',
  GOOGLE_GENERATIVE_AI_API_KEY: 'google_api_key',
  DASHSCOPE_API_KEY: 'dashscope_api_key',
};

/**
 * #3944: chat-key presence for the remediation planner, judged on the planes
 * both planner surfaces can rely on — process env, the FILE config plane,
 * and the gateway env snapshot (a DB-plane key that loadConfigWithEngine
 * already merged into the RUNNING gateway, i.e. a key that is actually
 * serving chat right now). NOT a raw `engine.getConfig()` read: a DB-only
 * key that never reached the gateway is unusable on planner paths, and the
 * raw read is what diverged autopilot from doctor pre-#3944 (doctor's
 * planner judges the file plane, #2662 is the same rule for embed keys).
 * The snapshot keeps both surfaces CONVERGENT — it flows through this one
 * shared helper — while a genuinely-usable key no longer reads as missing.
 * Shared by loadRecommendationContext and the autopilot dispatch loop.
 */
export function chatApiKeyConfigured(
  fileCfg: { anthropic_api_key?: unknown } | null | undefined,
): boolean {
  return !!(
    process.env.ANTHROPIC_API_KEY ||
    fileCfg?.anthropic_api_key ||
    getGatewayAnthropicKeySnapshot()
  );
}

export function embeddingProviderConfigured(
  embeddingModel: string | undefined,
  resolveKey: (envVar: string) => boolean,
): boolean {
  if (!embeddingModel) return false;
  let providerId: string;
  try {
    ({ providerId } = parseModelId(embeddingModel));
  } catch {
    return false; // malformed model id — mirror gateway.isAvailable's catch
  }
  const recipe = getRecipe(providerId);
  if (!recipe?.touchpoints?.embedding) return false;
  const required = recipe.auth_env?.required ?? [];
  return required.length === 0 ? true : required.every(resolveKey);
}

/** Minimal Check shape consumed by classifyChecks. Subset of doctor.ts's
 *  Check; we intentionally don't import from doctor.ts (would create a
 *  cycle: doctor → recommendations → doctor). */
export interface Check {
  name: string;
  status: 'ok' | 'warn' | 'fail';
}

/**
 * Shared recommendation generator for brain-health remediation.
 *
 * Consumed by both:
 *   - `gbrain doctor --remediation-plan` / `--remediate` (queue-based execution)
 *   - `gbrain features --auto-fix` (inline execution preserved per D15)
 *
 * Pure module — no engine I/O. Input is `BrainHealth` (already produced by
 * engine.getHealth()) + a `RecommendationContext` that names which prereqs
 * are met (API keys, repo path, source id).
 *
 * Three-state classification per check (D13):
 *   - `remediable`: a job exists AND prereqs are met. Emit it.
 *   - `human_only`:  no autofix (orphans archive, multi_source_drift,
 *                    eval_drift). Surface as informational; don't queue.
 *   - `blocked`:     autofix exists, prereq missing (e.g. missing API key
 *                    for embed). Surface with the missing prereq; don't queue.
 *
 * `maxReachableScore(health, classifications)` computes the score ceiling
 * assuming only `remediable` checks fire. Callers refuse `--target-score >
 * ceiling` so empty / API-key-missing brains don't spin forever.
 *
 * Plan: D13 + D14 + folded scope item A (cost-budget gate) from outside-voice
 * review. See ~/.claude/plans/system-instruction-you-are-working-fluttering-ocean.md.
 */

/**
 * v0.40.3.0: RemediationStep + RemediationSeverity + RemediationStatus
 * lifted to src/core/remediation-step.ts so other doctor checks (lint,
 * integrity, sync_failures) can emit RemediationStep without circular
 * importing brain-score code. Re-exported here for back-compat AND to
 * avoid forcing every importer to update the path in one PR.
 *
 * The `Remediation` name is deprecated as of v0.40.3.0; use
 * `RemediationStep` going forward. Same shape; rename was for clarity.
 */
export {
  type RemediationStep,
  type RemediationStep as Remediation,
  type RemediationSeverity,
  type RemediationStatus,
  makeRemediationStep,
  idempotencyKey as makeRemediationIdempotencyKey,
  canonicalJson,
} from './remediation-step.ts';
import type {
  RemediationStep,
  RemediationStatus,
  RemediationSeverity,
} from './remediation-step.ts';
// Internal alias so the existing implementation below keeps compiling
// without a sed pass. New code should reference RemediationStep directly.
type Remediation = RemediationStep;

export interface RecommendationContext {
  /** Source id this remediation is scoped to (multi-source brains). */
  sourceId?: string;
  /** Brain repo path on disk (for sync). */
  repoPath?: string;
  /** Configured embedding model id (e.g. 'openai:text-embedding-3-large'). */
  embeddingModel?: string;
  /** Configured embedding dimension (3072 / 1536 / 1024 / etc.). */
  embeddingDimensions?: number;
  /**
   * Whether the configured embedding provider is usable. For hosted providers
   * this means the required API key resolves; for local providers (ollama,
   * llama-server — empty auth_env.required) it's true once configured, no key
   * needed. Compute via `embeddingProviderConfigured()`.
   */
  embeddingProviderConfigured?: boolean;
  /**
   * E2: embeddings are off by choice (`init --no-embedding`). No embed step is
   * planned and `missing_embeddings` classifies as `human_only` with the
   * enable reason, never as a remediable or blocked gap.
   */
  embeddingsDisabled?: boolean;
  /** Configured chat / synthesis model id. */
  chatModel?: string;
  /** Whether the chat provider has a usable API key. */
  hasChatApiKey?: boolean;
  /**
   * D12: embedded chunks on pages with NO recorded embedding signature
   * (unknown provenance — possibly a previous model's space). Probed by the
   * engine-holding caller (loadRecommendationContext); this module is sync.
   * When > 0, the embed.stale step widens with includeNullSignature so the
   * cohort is re-embedded instead of grandfathered forever.
   */
  nullSignatureCohort?: number;
  /**
   * #5609: why `extract --stale` cannot run on this brain right now (it would
   * fail every dispatch). Probed by `staleExtractionBlocked()`; when set, the
   * `extract.stale` step is withheld and its check classifies as blocked.
   */
  staleExtractionBlocked?: string;
}

/** Triage result for one check. */
export interface CheckClassification {
  check: string;
  status: RemediationStatus;
  /** When status !== 'remediable', what's missing. */
  reason?: string;
}

/**
 * Generate ordered Remediation list from health snapshot + context.
 *
 * Sort: severity (critical > high > medium > low), then est_seconds asc.
 * Topological order over `depends_on` is the caller's job — they walk this
 * list and respect dependencies. Recommendation generator just picks order
 * within a strata.
 *
 * Returns ONLY `remediable` items. `blocked` items surface via
 * `classifyChecks()` and are rendered alongside the plan as informational.
 */
/**
 * Generalized (v0.41.18.0, A2 + codex finding #3): an optional third arg
 * lets callers inject RemediationStep entries discovered by doctor checks
 * outside this module's hardcoded planner. Without this, adding a
 * `Check.remediation` field to a new doctor check wouldn't auto-wire into
 * `gbrain doctor --remediation-plan` — the planner would just ignore it.
 *
 * Onboard's runRemediationPlan calls the 4 new check helpers (embed_staleness,
 * entity_link_coverage, timeline_coverage, takes_count) and threads their
 * RemediationStep[] outputs through this slot. Each helper produces its own
 * cheap query (D7 cheap-path preserved); aggregation happens in the caller.
 *
 * Sort + dedup applies across BOTH the hardcoded + extra entries: stable id
 * collisions resolve in favor of the hardcoded entry (legacy behavior wins),
 * which means extras only add coverage they're not duplicating.
 */
export function computeRecommendations(
  health: BrainHealth,
  ctx: RecommendationContext,
  extraRemediations: Remediation[] = [],
): Remediation[] {
  const out: Remediation[] = [];
  const source = ctx.sourceId ?? 'default';

  // ---------------------------------------------------------------------
  // embed.stale — missing embeddings AND/OR the NULL-signature cohort
  // (unknown-provenance vectors that the grandfather clause would otherwise
  // keep in a previous model's space forever). Critical: invisible to (or
  // wrong in) vector search.
  // ---------------------------------------------------------------------
  const nullSigCohort = ctx.nullSignatureCohort ?? 0;
  if ((health.missing_embeddings > 0 || nullSigCohort > 0) && ctx.embeddingProviderConfigured !== false && !ctx.embeddingsDisabled) {
    const params = {
      stale: true,
      sourceId: ctx.sourceId,
      // D12: widen only when the cohort exists — the params feed the
      // idempotency key, so a cohort appearing/clearing is semantically
      // different work (one-time dedupe miss on transition, accepted).
      ...(nullSigCohort > 0 && { includeNullSignature: true }),
    };
    const embedModel = ctx.embeddingModel ?? 'openai:text-embedding-3-large';
    const embedDims = ctx.embeddingDimensions ?? 3072;
    // Rough char estimate per chunk ~ 1.5k chars (chunker target). The
    // cohort is real re-embed spend too — count it (round-2 #12).
    const estChars = (health.missing_embeddings + nullSigCohort) * 1500;
    let est_usd_cost = 0;
    try {
      const priceLookup = lookupEmbeddingPrice(embedModel);
      if (priceLookup.kind === 'known') {
        est_usd_cost = estimateCostFromChars(estChars, priceLookup.pricePerMTok);
      }
    } catch {
      /* unknown model — leave at 0, surface as warning elsewhere */
    }
    const rationaleParts: string[] = [];
    if (health.missing_embeddings > 0) {
      rationaleParts.push(`${health.missing_embeddings} chunk${health.missing_embeddings === 1 ? '' : 's'} invisible to vector search`);
    }
    if (nullSigCohort > 0) {
      rationaleParts.push(`${nullSigCohort} chunk${nullSigCohort === 1 ? '' : 's'} with no recorded embedding signature (unknown provenance)`);
    }
    out.push({
      id: 'embed.stale',
      job: 'embed',
      params,
      idempotency_key: idemKey(source, 'embed', { ...params, embedModel, embedDims }),
      severity: 'critical',
      est_seconds: Math.min(3600, 5 + (health.missing_embeddings + nullSigCohort) * 0.05),
      est_usd_cost,
      depends_on: [],
      rationale: rationaleParts.join('; '),
      status: 'remediable',
    });
  }

  // ---------------------------------------------------------------------
  // backlinks.fix — dead links (refs to non-existent slugs)
  // ---------------------------------------------------------------------
  if (health.dead_links > 0 && ctx.repoPath) {
    const params = { action: 'fix', dir: ctx.repoPath };
    out.push({
      id: 'backlinks.fix',
      job: 'backlinks',
      params,
      idempotency_key: idemKey(source, 'backlinks', params),
      severity: 'high',
      est_seconds: Math.min(300, 10 + health.dead_links * 0.5),
      est_usd_cost: 0,
      depends_on: [],
      rationale: `${health.dead_links} dead link${health.dead_links === 1 ? '' : 's'}`,
      status: 'remediable',
    });
  }

  if (health.stale_pages > 0 && !ctx.staleExtractionBlocked) {
    const params = { stale: true, ...(ctx.sourceId ? { sourceId: ctx.sourceId } : {}) };
    out.push({
      id: 'extract.stale',
      job: 'extract',
      params,
      idempotency_key: idemKey(source, 'extract', params),
      severity: health.stale_pages > 50 ? 'high' : 'medium',
      est_seconds: Math.min(600, 30 + health.stale_pages * 0.01),
      est_usd_cost: 0,
      depends_on: [],
      rationale: `Materialize link + timeline edges for ${health.stale_pages} stale database page${health.stale_pages === 1 ? '' : 's'}`,
      status: 'remediable',
    });
  }

  // v0.41.18.0 (A2 + codex #3): merge caller-supplied extras. Hardcoded
  // entries win on id collision so legacy behavior is preserved when an
  // extra accidentally duplicates a hardcoded id.
  if (extraRemediations.length > 0) {
    const hardcodedIds = new Set(out.map((r) => r.id));
    for (const extra of extraRemediations) {
      if (!hardcodedIds.has(extra.id)) out.push(extra);
    }
  }

  // Sort: severity (critical first), then est_seconds ascending so quick
  // wins come first within a severity tier.
  const sevRank: Record<RemediationSeverity, number> = {
    critical: 0, high: 1, medium: 2, low: 3,
  };
  out.sort((a, b) => {
    const sd = sevRank[a.severity] - sevRank[b.severity];
    if (sd !== 0) return sd;
    return a.est_seconds - b.est_seconds;
  });

  return out;
}

/**
 * Triage every check from the doctor report into one of three buckets.
 * Used by the doctor remediation surface to surface what's not auto-fixable
 * (or auto-fixable-but-prereq-missing) as informational alongside the plan.
 *
 * Checks not listed here default to `human_only` (conservative — anything
 * the recommendation generator doesn't know about is treated as needing
 * operator judgment, not autonomous remediation).
 */
export function classifyChecks(
  checks: Check[],
  ctx: RecommendationContext,
): CheckClassification[] {
  return checks.map((c) => classifyOne(c, ctx));
}

function classifyOne(check: Check, ctx: RecommendationContext): CheckClassification {
  // Map check names to their remediation status. The recommendation
  // generator above handles `remediable`; this maps the rest.
  switch (check.name) {
    // --- remediable paths (matched by recommendation generator) ---
    case 'brain_score':
    case 'sync_freshness':
      if (!ctx.repoPath) {
        return { check: check.name, status: 'blocked', reason: 'no repo configured (set sync.repo_path)' };
      }
      return { check: check.name, status: 'remediable' };
    case 'missing_embeddings':
      if (ctx.embeddingsDisabled) {
        return { check: check.name, status: 'human_only', reason: 'embeddings disabled by choice (keyless brain); enabling them is the user\'s decision' };
      }
      if (ctx.embeddingProviderConfigured === false) {
        return { check: check.name, status: 'blocked', reason: 'embedding provider not configured' };
      }
      return { check: check.name, status: 'remediable' };
    case 'links_extraction_lag':
      if (ctx.staleExtractionBlocked) return { check: check.name, status: 'blocked', reason: ctx.staleExtractionBlocked };
      return { check: check.name, status: 'remediable' };
    case 'dead_links':
      if (!ctx.repoPath) {
        return { check: check.name, status: 'blocked', reason: 'no repo configured' };
      }
      return { check: check.name, status: 'remediable' };

    // --- human_only paths ---
    case 'orphan_pages':        // archive is product judgment, not maintenance
    case 'multi_source_drift':
    case 'eval_drift':
    case 'slug_fallback_audit':
    case 'whoknows_health':
    case 'rls_event_trigger':   // operator must intervene
    case 'reranker_health':
      return { check: check.name, status: 'human_only', reason: 'no autonomous remediation' };

    default:
      // Unknown checks: conservative default. Surfaces as informational
      // rather than blocking the loop.
      return { check: check.name, status: 'human_only', reason: 'unmapped check' };
  }
}

/**
 * Compute the score ceiling assuming only `remediable` checks fire.
 *
 * Each component of brain_score (embed_coverage 35, link_density 25,
 * timeline_coverage 15, no_orphans 15, no_dead_links 10) maps to a
 * remediable or non-remediable classification. Components without an
 * autofix path stay at their current score; remediable components can
 * theoretically reach their max.
 *
 * Returns the ceiling; --remediate refuses --target-score > ceiling
 * with a clear "this brain can only reach X without manual intervention"
 * error.
 */
export function maxReachableScore(
  health: BrainHealth,
  classifications: CheckClassification[],
): number {
  const classMap = new Map(classifications.map((c) => [c.check, c.status]));

  // Component → max contribution + remediability
  // Conservative: if the mapped check is NOT remediable, the component
  // stays at its current value (can't be lifted by autonomous action).
  let ceiling = 0;
  ceiling += pickMax(health.embed_coverage_score, 35, classMap.get('missing_embeddings'));
  ceiling += pickMax(health.link_density_score, 25, classMap.get('dead_links'));
  ceiling += pickMax(health.timeline_coverage_score, 15, undefined);  // no current autofix
  ceiling += pickMax(health.no_orphans_score, 15, classMap.get('orphan_pages'));
  ceiling += pickMax(health.no_dead_links_score, 10, classMap.get('dead_links'));
  return Math.min(100, Math.round(ceiling));
}

function pickMax(current: number, max: number, status: RemediationStatus | undefined): number {
  if (status === 'remediable') return max;
  return current;
}

// ---------------------------------------------------------------------
// Idempotency key construction (D9 — content-hash, no time-slot).
// Same params produce the same key across runs. Terminal-row replay
// (a completed/failed row holds the key forever) rotates the key to
// `:r:<doctor_run_id>` in the --remediate loop (#3626, remediation/run.ts).
// ---------------------------------------------------------------------

function idemKey(source: string, job: string, params: Record<string, unknown>): string {
  return `${source}:${job}:${sha8(canonicalJson(params))}`;
}

function sha8(s: string): string {
  return createHash('sha256').update(s).digest('hex').slice(0, 8);
}

function canonicalJson(value: unknown): string {
  if (value === null || typeof value !== 'object') return JSON.stringify(value);
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
  const keys = Object.keys(value as Record<string, unknown>).sort();
  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson((value as Record<string, unknown>)[k])}`).join(',')}}`;
}

/**
 * Returns the per-recommendation USD cost ceiling for an Anthropic-model
 * job. Used by synthesize/patterns/consolidate cost estimates.
 *
 * `estCallsPerInvocation` is a per-job heuristic (e.g. synthesize ~
 * 20 calls per invocation; patterns ~ 5). Multiplied by per-call token
 * budget × Anthropic-model price.
 */
export function estimateAnthropicCost(
  modelId: string,
  estCallsPerInvocation: number,
  estInputTokensPerCall = 5_000,
  estOutputTokensPerCall = 1_000,
): number {
  const pricing = canonicalLookup(modelId);
  if (!pricing) return 0;
  const inputCost = (estInputTokensPerCall * estCallsPerInvocation / 1_000_000) * pricing.input;
  const outputCost = (estOutputTokensPerCall * estCallsPerInvocation / 1_000_000) * pricing.output;
  return Number((inputCost + outputCost).toFixed(2));
}