Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.6 KB
Raw Blame
/**
 * gbrain features — Scan brain usage and recommend unused features.
 *
 * Usage:
 *   gbrain features [--json] [--auto-fix] [--help]
 */

import { gbrainPath } from '../core/config.ts';
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
import { join } from 'path';
import type { BrainEngine } from '../core/engine.ts';
import { heartbeatPath } from './integrations.ts';
import { VERSION } from '../version.ts';
import { cliRenderContext, renderNotice, type Notice } from '../core/agent-output.ts';
import { writeCliNotices } from '../core/interop-notices.ts';
import { embeddingsDisabled } from '../core/embedding-disabled.ts';

// --- Types ---

type FeaturePriority = 1 | 2;

interface FeatureRecommendation {
  id: string;
  priority: FeaturePriority;
  title: string;
  pitch: string;
  command: string;
  auto_fixable: boolean;
}

interface FeatureOffersFile {
  lastVersion: string;
  lastScan: string;
  declined: Record<string, { at: string; version: string }>;
  accepted: Record<string, { at: string; version: string }>;
}

interface FeatureScanResult {
  version: string;
  scan_ts: string;
  brain_score: number;
  recommendations: FeatureRecommendation[];
}

// --- Embedded recipe metadata (binary-safe, no disk reads) ---

// Secret names MUST match the corresponding recipes/<id>.md frontmatter, and are
// treated as ANY-of, not all-of: a recipe whose auth is an `any_of` health check
// (ClawVisor OR direct OAuth) is configured as soon as one path is present.
// Pinned by test/features-recipe-secrets.test.ts.
export const RECIPE_META = [
  { id: 'email-to-brain', name: 'Email to Brain', secrets: ['CLAWVISOR_AGENT_TOKEN', 'GOOGLE_CLIENT_ID'] },
  { id: 'calendar-to-brain', name: 'Calendar Sync', secrets: ['CLAWVISOR_AGENT_TOKEN', 'GOOGLE_CLIENT_ID'] },
  { id: 'x-to-brain', name: 'X/Twitter to Brain', secrets: ['X_API_BEARER_TOKEN'] },
  { id: 'twilio-voice-brain', name: 'Voice to Brain', secrets: ['TWILIO_AUTH_TOKEN'] },
  { id: 'meeting-sync', name: 'Meeting Sync', secrets: ['CIRCLEBACK_TOKEN'] },
  { id: 'credential-gateway', name: 'Credential Gateway', secrets: ['CLAWVISOR_AGENT_TOKEN', 'GOOGLE_CLIENT_ID'] },
  { id: 'ngrok-tunnel', name: 'Ngrok Tunnel', secrets: ['NGROK_AUTHTOKEN'] },
] as const;

// --- Persistence ---

function offersPath(): string {
  return gbrainPath('feature-offers.json');
}

function loadOffers(): FeatureOffersFile {
  try {
    const raw = readFileSync(offersPath(), 'utf-8');
    return JSON.parse(raw);
  } catch {
    return { lastVersion: '', lastScan: '', declined: {}, accepted: {} };
  }
}

function saveOffers(offers: FeatureOffersFile) {
  try {
    mkdirSync(gbrainPath(), { recursive: true });
    writeFileSync(offersPath(), JSON.stringify(offers, null, 2));
  } catch { /* best-effort */ }
}

// Real-world check: did this integration actually get set up?
// Heartbeat files are written by Hermes during install (and by other hosts),
// so they are the source of truth for "is this wired up" — not just whether
// a secret env var happens to be exported in this shell.
function integrationHeartbeatExists(recipeId: string): boolean {
  try {
    const heartbeat = heartbeatPath(recipeId);
    if (!existsSync(heartbeat)) return false;
    const lines = readFileSync(heartbeat, 'utf-8')
      .split('\n')
      .map(l => l.trim())
      .filter(Boolean);
    return lines.some(line => {
      try {
        const evt = JSON.parse(line);
        return evt?.event === 'setup_complete';
      } catch {
        return false;
      }
    });
  } catch {
    return false;
  }
}

function shouldPitch(rec: FeatureRecommendation, offers: FeatureOffersFile, currentVersion: string): boolean {
  if (rec.priority === 1) return true; // always pitch data quality
  const majorMinor = currentVersion.split('.').slice(0, 2).join('.');
  const declined = offers.declined[rec.id];
  if (declined && declined.version.startsWith(majorMinor)) return false;
  return true;
}

// --- Scanners ---

export async function scanFeatures(engine: BrainEngine): Promise<FeatureScanResult> {
  const stats = await engine.getStats();
  const health = await engine.getHealth();
  const recommendations: FeatureRecommendation[] = [];
  const keyless = await embeddingsDisabled(engine);

  // P1: Missing embeddings (never on a keyless-by-choice brain: E2)
  if (health.missing_embeddings > 0 && !keyless) {
    recommendations.push({
      id: 'missing-embeddings', priority: 1,
      title: 'Fix Missing Embeddings',
      pitch: `${health.missing_embeddings} chunks invisible to semantic search. One command fixes it.`,
      command: 'gbrain embed --stale',
      auto_fixable: true,
    });
  }

  // P1: Dead links
  if (health.dead_links > 0) {
    recommendations.push({
      id: 'dead-links', priority: 1,
      title: 'Fix Dead Links',
      pitch: `${health.dead_links} links pointing to non-existent pages.`,
      command: 'gbrain check-backlinks fix',
      auto_fixable: false,
    });
  }

  // P2: skip if brain too new
  if (stats.page_count >= 3) {
    // Zero links
    if (stats.link_count === 0 && stats.page_count > 5) {
      recommendations.push({
        id: 'zero-links', priority: 2,
        title: 'Build Link Graph',
        pitch: `${stats.page_count} pages but 0 links. Your brain is a flat file cabinet, not a knowledge graph.`,
        command: 'gbrain extract links',
        auto_fixable: true,
      });
    }

    // Zero timeline
    if (stats.timeline_entry_count === 0 && stats.page_count > 5) {
      recommendations.push({
        id: 'zero-timeline', priority: 2,
        title: 'Extract Timeline',
        pitch: `No structured timeline entries. Your brain can't answer "when did X happen?"`,
        command: 'gbrain extract timeline',
        auto_fixable: true,
      });
    }

    // Low embed coverage
    if (health.embed_coverage < 0.9 && health.embed_coverage > 0 && !keyless) {
      const pct = (health.embed_coverage * 100).toFixed(0);
      recommendations.push({
        id: 'low-coverage', priority: 2,
        title: 'Improve Embedding Coverage',
        pitch: `${pct}% embed coverage. ${health.missing_embeddings} chunks invisible to semantic search.`,
        command: 'gbrain embed --stale',
        auto_fixable: true,
      });
    }

    // Unconfigured integrations
    // ANY-of: a recipe is configured once one of its declared secrets is present.
    // `every` made any recipe with alternative auth paths permanently
    // "unconfigured", since a ClawVisor user never sets GOOGLE_CLIENT_ID and
    // vice versa.
    // A recipe also counts as configured if a real setup heartbeat file exists
    // on disk (wired up via Hermes/another host). Env-only checks produced
    // false "not configured" reports for integrations that were actually
    // installed.
    const unconfigured = RECIPE_META.filter(r => {
      const envOk = r.secrets.some(s => !!process.env[s]);
      if (envOk) return false;
      return !integrationHeartbeatExists(r.id);
    });
    if (unconfigured.length > 0) {
      recommendations.push({
        id: 'no-integrations', priority: 2,
        title: 'Set Up Integrations',
        pitch: `${unconfigured.length} integration recipes available but not configured: ${unconfigured.map(r => r.name).join(', ')}.`,
        command: `gbrain integrations list`,
        auto_fixable: false,
      });
    }

    // No sync configured. Modern sync anchors on sources.local_path; the global
    // sync.repo_path is only the legacy single-source fallback, which non-default
    // sources never set (#4767). Legacy key first so it short-circuits the query.
    try {
      const syncRepo = await engine.getConfig('sync.repo_path');
      if (!syncRepo && (await engine.listAllSources({ localPathOnly: true })).length === 0) {
        recommendations.push({
          id: 'no-sync', priority: 2,
          title: 'Configure Sync',
          pitch: `Brain not syncing from git. Changes in your repo don't reach your brain.`,
          command: 'gbrain sync --repo <path>',
          auto_fixable: false,
        });
      }
    } catch { /* skip */ }
  }

  return {
    version: VERSION,
    scan_ts: new Date().toISOString(),
    brain_score: (health as any).brain_score ?? 0,
    recommendations,
  };
}

/** The recommendations `gbrain features` would pitch to this user now; reads the offer state, never writes it. */
export async function pitchableFeatures(engine: BrainEngine): Promise<FeatureRecommendation[]> {
  const scan = await scanFeatures(engine);
  const offers = loadOffers();
  return scan.recommendations.filter(r => shouldPitch(r, offers, scan.version));
}

// --- Auto-fix ---

async function executeAutoFix(rec: FeatureRecommendation, engine: BrainEngine): Promise<{ success: boolean; output: string }> {
  try {
    switch (rec.id) {
      case 'missing-embeddings':
      case 'low-coverage': {
        // X6 (#4599): go through the CORE seam, not the CLI wrapper —
        // runEmbed maps a stall-watchdog abort to process.exit(1), which
        // would kill this whole auto-fix loop mid-run. The core returns an
        // error RESULT; assertEmbedNotStalled turns it into a throw that
        // this function's catch reports as { success: false }.
        const { runEmbedCore } = await import('./embed.ts');
        const { assertEmbedNotStalled } = await import('../core/embed-stall.ts');
        const result = await runEmbedCore(engine, { stale: true, singleFlight: true });
        assertEmbedNotStalled(result);
        return { success: true, output: 'Stale embeddings refreshed' };
      }
      case 'zero-links': {
        const { runExtract } = await import('./extract.ts');
        await runExtract(engine, ['links']);
        return { success: true, output: 'Links extracted' };
      }
      case 'zero-timeline': {
        const { runExtract } = await import('./extract.ts');
        await runExtract(engine, ['timeline']);
        return { success: true, output: 'Timeline entries extracted' };
      }
      default:
        return { success: false, output: 'No auto-fix available' };
    }
  } catch (e) {
    return { success: false, output: e instanceof Error ? e.message : String(e) };
  }
}

// --- Main command ---

export async function runFeatures(engine: BrainEngine, args: string[]) {
  if (args.includes('--help') || args.includes('-h')) {
    console.log('Usage: gbrain features [--json] [--auto-fix [--yes]]\n\nScan brain usage and recommend unused features.\n\n  --json       Output as JSON (for agents)\n  --auto-fix   Automatically fix all auto-fixable issues\n  --yes        Authorize the paid embedding auto-fix (non-interactive runs need it)');
    return;
  }

  const jsonMode = args.includes('--json');
  const autoFix = args.includes('--auto-fix');

  const scan = await scanFeatures(engine);
  const offers = loadOffers();
  const pitchable = scan.recommendations.filter(r => shouldPitch(r, offers, scan.version));

  if (pitchable.length === 0) {
    if (jsonMode) {
      console.log(JSON.stringify({ ...scan, recommendations: [] }, null, 2));
    } else {
      console.log(`\nBrain score: ${scan.brain_score}/100. All features adopted. Nothing to recommend.`);
    }
    return;
  }

  // F7: the auto-fix suggestion is a coaching notice on every surface (it was
  // printed only on a terminal); --json carries it under `notices`.
  const autoFixNotice = autoFix ? null : featuresAutoFixNotice(pitchable);
  if (autoFix && pitchable.some(r => r.auto_fixable && PAID_AUTO_FIX_IDS.has(r.id))) {
    const { requireEmbedBackfillConsent } = await import('../core/embed-consent.ts');
    const { isConsentRefusal, printConsentRefusal } = await import('../core/consent.ts');
    const { setCliExitVerdict } = await import('../core/cli-force-exit.ts');
    try {
      await requireEmbedBackfillConsent(engine, { command: 'features', argv: ['gbrain', 'features', ...args.filter(a => a !== '--yes')], args, scope: {} });
    } catch (e) {
      if (!isConsentRefusal(e)) throw e;
      setCliExitVerdict(printConsentRefusal(e, { json: jsonMode }));
      return;
    }
  }
  if (jsonMode) {
    const fixResults: Record<string, { success: boolean; output: string }> = {};
    if (autoFix) {
      for (const rec of pitchable.filter(r => r.auto_fixable)) {
        fixResults[rec.id] = await executeAutoFix(rec, engine);
        offers.accepted[rec.id] = { at: new Date().toISOString().slice(0, 10), version: scan.version };
      }
    }
    console.log(JSON.stringify({ ...scan, recommendations: pitchable, auto_fix_results: autoFix ? fixResults : undefined,
      ...(autoFixNotice ? { notices: [renderNotice(autoFixNotice, cliRenderContext())] } : {}) }, null, 2));
    offers.lastVersion = scan.version;
    offers.lastScan = scan.scan_ts;
    saveOffers(offers);
    return;
  }

  // Human-readable output
  console.log(`\nBrain score: ${scan.brain_score}/100\n`);

  const p1 = pitchable.filter(r => r.priority === 1);
  const p2 = pitchable.filter(r => r.priority === 2);

  if (p1.length > 0) {
    console.log('DATA QUALITY (fix these first):');
    for (const rec of p1) {
      console.log(`  ${rec.title}: ${rec.pitch}`);
      console.log(`    Fix: ${rec.command}`);
    }
    console.log('');
  }

  if (p2.length > 0) {
    console.log('UNUSED FEATURES:');
    for (const rec of p2) {
      console.log(`  ${rec.title}: ${rec.pitch}`);
      console.log(`    Try: ${rec.command}`);
    }
    console.log('');
  }

  if (autoFix) {
    console.log('Running auto-fix...');
    for (const rec of pitchable.filter(r => r.auto_fixable)) {
      const result = await executeAutoFix(rec, engine);
      console.log(`  ${result.success ? 'OK' : 'FAIL'}: ${rec.title} — ${result.output}`);
      offers.accepted[rec.id] = { at: new Date().toISOString().slice(0, 10), version: scan.version };
    }
  } else if (autoFixNotice) {
    writeCliNotices([autoFixNotice]);
  }

  offers.lastVersion = scan.version;
  offers.lastScan = scan.scan_ts;
  saveOffers(offers);
}

/** Auto-fixes that embed (paid): they need the user's approval (--yes, --max-usd, --max-cost, tokenmax or a preapproval). */
const PAID_AUTO_FIX_IDS: ReadonlySet<string> = new Set(['missing-embeddings', 'low-coverage']);

/** F7: the `features_auto_fix` coaching notice; null when nothing is auto-fixable. Pure: the CLI and the stdio onboarding cache share it. */
export function featuresAutoFixNotice(pitchable: readonly FeatureRecommendation[]): Notice | null {
  const fixable = pitchable.filter(r => r.auto_fixable);
  if (fixable.length === 0) return null;
  const paid = fixable.some(r => PAID_AUTO_FIX_IDS.has(r.id));
  return {
    code: 'features_auto_fix', kind: 'coaching',
    why: `${fixable.length} recommendation(s) can be fixed automatically: ${fixable.map(r => r.title).join(', ')}.`,
    fix: {
      argv: ['gbrain', 'features', '--auto-fix', ...(paid ? ['--yes'] : [])], consent: paid ? ['paid'] : [], actor: 'agent', requires_exclusive: false,
      why: paid ? 'Runs the fixes; refreshing embeddings calls the configured embedding provider (a small paid cost).' : 'Runs the fixes (link and timeline extraction; no paid calls).',
      ...(paid ? { user_message: 'gbrain can fill in missing embeddings for your notes; it costs a little in embedding API calls. OK to run it?' } : {}),
    },
  };
}

/** Lightweight features teaser for doctor output */
export async function featuresTeaserForDoctor(engine: BrainEngine): Promise<string | null> {
  try {
    const health = await engine.getHealth();
    const parts: string[] = [];
    if (health.missing_embeddings > 0 && !await embeddingsDisabled(engine)) parts.push(`${health.missing_embeddings} missing embeddings`);
    if (health.dead_links > 0) parts.push(`${health.dead_links} dead links`);
    if (parts.length === 0) return null;
    return `Tip: ${parts.join(', ')}. Run 'gbrain features' to fix.`;
  } catch {
    return null;
  }
}