Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* 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;
}
}