Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.4 KB
Raw Blame
/**
 * `skill_resolver` (GBRA-377 PR B): the skill-resolver hook lane that
 * `gbrain setup <claude-code|codex|hermes> --skill-loading resolve` turns on
 * (src/core/skills/resolver/hook-lane.ts). Per harness it reports the lane's
 * hook (wired, untrusted in Codex or unapproved in Hermes, outdated when it predates the SessionStart
 * compaction reset, or missing), each catalog's freshness
 * (the content tier: source re-read, index re-hashed) and the recent
 * outcomes and error codes from the lane log. It emits nothing when the
 * resolver is not configured: no keys, no hook, no catalog and no lane log.
 * harness_wiring carries the same view in its details.
 *
 * Read-only apart from catalogStatus's session sweep; warns, never fails.
 */
import { join } from 'node:path';
import type { Check } from '../../doctor.ts';
import { doctorVerify } from '../check-fix.ts';
import { configDir } from '../../../core/config.ts';
import { catalogStatus, listCatalogs } from '../../../core/skills/resolver/build.ts';
import { logsDir } from '../../../core/skills/resolver/paths.ts';
import { LANE_LOG, readRecentDailyLog } from '../../../core/skills/resolver/daily-log.ts';
import { CLAUDE_PLUGINS_CATALOG, projectCatalogPrefix, userCatalogName } from '../../../core/skills/resolver/hook-lane.ts';
import { readResolverConfig, resolverHarnesses } from '../../../core/setup/skill-resolver-config.ts';
import { inspectSkillResolverHook, type ResolverHarness, type ResolverHookState } from '../../../core/setup/skill-resolver-hook.ts';
import { describeOpenclawSkill, openclawSkillView, type OpenclawSkillView } from './skill-resolver-openclaw.ts';
import { describePiSkillView, piSkillView, type PiSkillView } from './skill-resolver-pi.ts';
import { cursorSkillView, describeCursorSkillView, type CursorSkillView } from './skill-resolver-cursor.ts';

const name = 'skill_resolver';
const HARNESSES: ResolverHarness[] = ['claude-code', 'codex', 'hermes'];
/** Lane-log lines doctor reads (the newest), and the tail it reads them from. */
const RECENT_LINES = 200;
const LOG_TAIL_BYTES = 64 * 1024;

export interface SkillResolverCatalogView { name: string; fresh: boolean | null; stale_reason: string | null; skills: number }
export interface SkillResolverHarnessView { harness: ResolverHarness; on: boolean; hook: ResolverHookState; catalogs: SkillResolverCatalogView[] }
export interface SkillResolverView {
  config: 'ok' | 'absent' | 'unreadable';
  harnesses: SkillResolverHarnessView[];
  recent: { turns: number; outcomes: Record<string, number>; errors: Record<string, number> };
  /** The OpenClaw plugin (gbrain setup openclaw --skill-loading resolve|shadow), when any of it exists. */
  openclaw?: OpenclawSkillView;
  /** The Pi extension (gbrain setup pi --skill-loading resolve), when any of it exists. */
  pi?: PiSkillView;
  /** Cursor's pinned-skills rules (gbrain setup cursor --skill-loading resolve), when a project is recorded. */
  cursor?: CursorSkillView;
}

function recentLane(home: string): SkillResolverView['recent'] | null {
  const text = readRecentDailyLog(logsDir(home), LANE_LOG, LOG_TAIL_BYTES);
  if (text === null) return null;
  const outcomes: Record<string, number> = {};
  const errors: Record<string, number> = {};
  const lines = text.split('\n').filter(Boolean).slice(-RECENT_LINES);
  let turns = 0;
  for (const line of lines) {
    let j: { outcome?: unknown; code?: unknown };
    try { j = JSON.parse(line); } catch { continue; }
    if (typeof j.outcome !== 'string') continue;
    turns++;
    outcomes[j.outcome] = (outcomes[j.outcome] ?? 0) + 1;
    if (typeof j.code === 'string') errors[j.code] = (errors[j.code] ?? 0) + 1;
  }
  return { turns, outcomes, errors };
}

/** A catalog a turn can rank with no project: the user catalog, and for Claude Code the plugins catalog. */
const isTurnCatalog = (harness: ResolverHarness, n: string) => n === userCatalogName(harness) || (harness === 'claude-code' && n === CLAUDE_PLUGINS_CATALOG);

/** The resolver's state for doctor, or null when nothing of it exists. */
export async function skillResolverView(home = configDir()): Promise<SkillResolverView | null> {
  const cfg = readResolverConfig(home);
  const on = cfg.state === 'ok' ? resolverHarnesses(cfg.doc) : [];
  const catalogs = listCatalogs(home);
  const recent = recentLane(home);
  const harnesses: SkillResolverHarnessView[] = [];
  for (const harness of HARNESSES) {
    const hook = inspectSkillResolverHook(harness).state;
    const mine = catalogs.filter((n) => isTurnCatalog(harness, n) || n.startsWith(projectCatalogPrefix(harness)));
    if (!on.includes(harness) && hook === 'absent' && mine.length === 0) continue;
    const views: SkillResolverCatalogView[] = [];
    for (const name of mine) {
      const s = await catalogStatus(name, { home });
      views.push({ name, fresh: s.fresh, stale_reason: s.stale_reason, skills: s.receipt?.skill_count ?? 0 });
    }
    harnesses.push({ harness, on: on.includes(harness), hook, catalogs: views });
  }
  const openclaw = await openclawSkillView(home);
  const pi = await piSkillView(home);
  const cursor = await cursorSkillView(home);
  if (harnesses.length === 0 && !recent && !(cfg.state === 'ok' && on.length) && !openclaw && !pi && !cursor) return null;
  return { config: cfg.state, harnesses, recent: recent ?? { turns: 0, outcomes: {}, errors: {} }, ...(openclaw ? { openclaw } : {}), ...(pi ? { pi } : {}), ...(cursor ? { cursor } : {}) };
}

const setupArgv = (harness: string) => ['gbrain', 'setup', harness, '--skill-loading', 'resolve'];

/** One line for harness_wiring's message. */
export function describeSkillResolver(v: SkillResolverView): string {
  if (v.config === 'unreadable') return 'Skill resolver: the config file cannot be read (skill_resolver_config_unreadable).';
  const parts = v.harnesses.map((h) => {
    const user = h.catalogs.find((c) => c.name === userCatalogName(h.harness)) ?? h.catalogs.find((c) => isTurnCatalog(h.harness, c.name));
    const fresh = !user ? 'no catalog' : user.fresh ? 'fresh' : `stale (${user.stale_reason})`;
    return `${h.harness} ${h.on ? 'on' : 'off'}, hook ${h.hook}, ${user?.skills ?? 0} skills, ${fresh}`;
  });
  const errs = Object.entries(v.recent.errors).map(([c, n]) => `${c} x${n}`).join(', ');
  const oc = v.openclaw ? `; ${describeOpenclawSkill(v.openclaw).line}` : '';
  const pi = v.pi ? `; ${describePiSkillView(v.pi).line}` : '';
  const cursor = v.cursor ? `; ${describeCursorSkillView(v.cursor).line}` : '';
  return `Skill resolver: ${parts.join('; ') || (v.openclaw || v.pi || v.cursor ? 'no hook harness on' : 'no harness on')}${v.recent.turns ? `; last ${v.recent.turns} turns${errs ? ` with ${errs}` : ' without errors'}` : ''}${oc}${pi}${cursor}.`;
}

export function skillResolverCheck(v: SkillResolverView | null): Check | null {
  if (!v) return null;
  const details = { ...v };
  if (v.config === 'unreadable') {
    return { name, status: 'warn', message: `${describeSkillResolver(v)} The hook lane prints nothing until it can read it.`, details: { ...details, code: 'skill_resolver_config_unreadable' },
      fix: { consent: [], actor: 'user', requires_exclusive: false, verify: doctorVerify(name), docs: 'docs/guides/skill-resolver.md#skill_resolver_config_unreadable',
        why: 'gbrain never rewrites a config file it cannot parse; the lane and setup leave it alone.',
        user_message: `gbrain's config file (${join(configDir(), 'config.json')}) is not valid JSON, so the skill resolver is paused. Fix or move it, then run: gbrain setup <claude-code|codex|hermes> --skill-loading resolve` } };
  }
  const broken = v.harnesses.find((h) => h.on && (h.hook !== 'wired' || !h.catalogs.some((c) => isTurnCatalog(h.harness, c.name))));
  if (broken) {
    const what = broken.hook === 'outdated' ? `its hook has no SessionStart entry (installed before the compaction reset), so skills offered before a compaction are not offered again; ${setupArgv(broken.harness).join(' ')} adds it`
      : `${broken.hook === 'untrusted' ? (broken.harness === 'hermes' ? 'its Hermes hook is not approved in shell-hooks-allowlist.json (hermes hooks doctor shows it)' : 'its Codex hook is not trusted') : broken.hook === 'absent' ? 'its hook entry is missing' : 'its user catalog is missing'}, so no skills block is added`;
    return { name, status: 'warn', message: `${describeSkillResolver(v)} ${broken.harness}: the resolver is on but ${what}.`, details,
      fix: { argv: setupArgv(broken.harness), consent: ['persistent_install'], actor: 'agent', requires_exclusive: false, verify: doctorVerify(name),
        why: `Rebuilds the ${broken.harness} user catalog and rewrites only the skill-resolver hook entry; --skill-loading off removes it instead.` } };
  }
  const oc = v.openclaw ? describeOpenclawSkill(v.openclaw).problem : null;
  if (oc) {
    return { name, status: 'warn', message: `${describeSkillResolver(v)} OpenClaw: ${oc.what}.`, details: { ...details, code: oc.code },
      fix: { argv: ['gbrain', 'setup', 'openclaw', '--skills-index-only'], consent: [], actor: 'agent', requires_exclusive: false, verify: doctorVerify(name), docs: `docs/guides/skill-resolver.md#${oc.code}`,
        why: 'Rebuilds the OpenClaw catalogs, the library and the plugin state without running any OpenClaw command; gbrain setup openclaw --skill-loading resolve reinstalls the plugin itself.' } };
  }
  const pi = v.pi ? describePiSkillView(v.pi).problem : null;
  if (pi) {
    return { name, status: 'warn', message: `${describeSkillResolver(v)} Pi: ${pi.what}.`, details: { ...details, code: pi.code },
      fix: { argv: setupArgv('pi'), consent: ['persistent_install'], actor: 'agent', requires_exclusive: false, verify: doctorVerify(name), docs: `docs/guides/skill-resolver.md#${pi.code}`,
        why: 'Rebuilds the pi-user catalog, the library and the state, and rewrites the Pi extension; gbrain setup pi --skill-loading off removes it instead.' } };
  }
  const cursor = v.cursor ? describeCursorSkillView(v.cursor).problem : null;
  if (cursor) {
    return { name, status: 'warn', message: `${describeSkillResolver(v)} Cursor: ${cursor.what}.`, details: { ...details, code: cursor.code },
      fix: { argv: setupArgv('cursor'), consent: ['persistent_install'], actor: 'agent', requires_exclusive: false, verify: doctorVerify(name), docs: `docs/guides/skill-resolver.md#${cursor.code}`,
        why: `Run it in ${cursor.project}: it rebuilds that project's catalog and rewrites its pinned-skills rule; gbrain setup cursor --skill-loading off there removes them instead.` } };
  }
  return { name, status: 'ok', message: describeSkillResolver(v), details };
}