Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.8 KB
Raw Blame
/**
 * SkillOpt dream-cycle phase wrapper.
 *
 * Walks every skill that has `skillopt-benchmark.jsonl` AND a stale
 * `last_run_at` (>7d by default; configurable). Per-skill cap $0.50;
 * brain-wide cap $2.00 (both configurable). Bundled-skill safety
 * (D16): bundled skills never auto-mutate — proposed.md is written
 * to `~/.gbrain/skillopt-proposed-bundled/<skill>.md` for review.
 *
 * Per-skill last-run state lives in `config` table keyed
 * `cycle.skillopt.last_run.<skill>` so the cycle is cheap to re-enter
 * (don't re-run the same skill every cycle). An `errored` run (or a thrown
 * error) does NOT bank last_run: it records `cycle.skillopt.last_error.<skill>`
 * instead, and the skill is retried no sooner than 24h after that error.
 * Each result row forwards the run's abort_reason / abort_detail / run_id /
 * remediation so the cycle report says why a skill failed.
 *
 * Admission (#5585): when one call of the run can never fit the per-skill cap
 * (preflight's `reservation_exceeds_cap: ...` abort, raised before any model call) the
 * skill is recorded `skipped_budget` with remediation, and
 * `cycle.skillopt.last_skip.<skill>` stores a fingerprint of everything the
 * reservation check prices: the resolved optimizer, target and judge models,
 * `cycle.skillopt.per_skill_cap_usd`, `skillopt.reflect_max_tokens`,
 * `pricing.overrides`, the gbrain version (built-in prices and default caps)
 * and the skill's benchmark (per-task judge models); the skill is not retried
 * until one of them changes. Models resolve once per cycle through `resolveSkillOptModels`; the
 * models banner prints once and each run prints only rows that differ.
 *
 * Each per-skill invocation runs with epochs=1 (incremental nightly
 * improvement, not full optimization). Users who want a full multi-epoch
 * run invoke `gbrain skillopt <name> --epochs N` directly.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import type { BrainEngine } from '../engine.ts';
import { autoDetectSkillsDirReadOnly } from '../repo-root.ts';
import { StructuredAgentError } from '../errors.ts';
import { buildModelsPlan, formatModelsBanner, resolveSkillOptModels, skillOptModelOpts } from './models-plan.ts';
import { runSkillOpt } from './orchestrator.ts';
import { REFLECT_MAX_TOKENS_CONFIG_KEY } from './output-cap.ts';
import { parseSplit } from './benchmark.ts';
import { gcStaleCheckpoints } from './checkpoint.ts';
import { sha8 } from './audit.ts';
import { VERSION } from '../../version.ts';
import { buildRemediation, errorCode } from './remediation.ts';
import type { SkillOptOpts } from './types.ts';

export interface SkilloptPhaseOpts {
  engine: BrainEngine;
  dryRun?: boolean;
  signal?: AbortSignal;
  /**
   * issue #2860 — `gbrain dream --phase skillopt --once`. Bypasses the
   * `cycle.skillopt.enabled` feature flag for THIS call only; never reads
   * or writes config. Per-skill + brain-wide cost caps still apply.
   */
  once?: boolean;
}

export interface SkilloptPhaseResult {
  phase: 'skillopt';
  status: 'ok' | 'skipped' | 'warn' | 'fail';
  duration_ms: number;
  summary: string;
  details: Record<string, unknown>;
}

interface SkillCandidate {
  name: string;
  benchmarkPath: string;
  lastRunAt: number | null;
}

interface SkillResult {
  skill: string;
  outcome: string;
  cost_usd: number;
  reason?: string;
  abort_reason?: string;
  abort_detail?: string;
  run_id?: string;
  remediation?: Array<{ code: string; fix: string; docs: string }>;
}

/** Default per-skill cost cap for the phase. */
const DEFAULT_PER_SKILL_CAP_USD = 0.50;
/** Default brain-wide cost cap for one cycle. */
const DEFAULT_BRAIN_WIDE_CAP_USD = 2.00;
/** Default stale threshold (skip skills that ran within this window). */
const DEFAULT_STALE_DAYS = 7;
/** An errored skill is retried no sooner than this after its last error. */
const ERROR_RETRY_MS = 24 * 3600 * 1000;

export async function runPhaseSkillopt(opts: SkilloptPhaseOpts): Promise<SkilloptPhaseResult> {
  const { engine } = opts;
  const start = Date.now();

  // Read the feature flag. Default OFF.
  let enabled = false;
  try {
    const v = await engine.getConfig('cycle.skillopt.enabled');
    enabled = v === 'true';
  } catch { /* default OFF */ }
  if (!enabled) {
    if (!opts.once) {
      return {
        phase: 'skillopt',
        status: 'skipped',
        duration_ms: Date.now() - start,
        summary: 'feature flag off (gbrain config set cycle.skillopt.enabled true to enable)',
        details: { reason: 'feature_flag_off' },
      };
    }
    process.stderr.write(
      '[dream] --once: cycle.skillopt.enabled is false but ' +
      '--phase skillopt --once forces this run (config untouched)\n',
    );
  }

  // Per-skill + brain-wide cost caps.
  const perSkillCap = await readNumericConfig(engine, 'cycle.skillopt.per_skill_cap_usd', DEFAULT_PER_SKILL_CAP_USD);
  const brainWideCap = await readNumericConfig(engine, 'cycle.skillopt.brain_wide_cap_usd', DEFAULT_BRAIN_WIDE_CAP_USD);
  const staleDays = await readNumericConfig(engine, 'cycle.skillopt.stale_days', DEFAULT_STALE_DAYS);

  // Locate skills dir.
  const detected = autoDetectSkillsDirReadOnly(process.cwd());
  const skillsDir = detected.dir;
  if (!skillsDir) {
    return {
      phase: 'skillopt',
      status: 'skipped',
      duration_ms: Date.now() - start,
      summary: 'no skills directory found',
      details: { reason: 'no_skills_dir' },
    };
  }

  // Cycle runs never resume, so kept checkpoints (errored / early-stopped)
  // are reclaimed here once they age past the 7-day window.
  if (!opts.dryRun) {
    try { gcStaleCheckpoints(skillsDir); } catch { /* best effort; never blocks the phase */ }
  }

  // Resolve models once. Tiers default to deep/subagent/reasoning.
  const models = await resolveSkillOptModels(engine);
  const admission = {
    optimizer: models.optimizer.model,
    target: models.target.model,
    judge: models.judge.model,
    per_skill_cap_usd: perSkillCap,
    reflect_max_tokens: await engine.getConfig(REFLECT_MAX_TOKENS_CONFIG_KEY).catch(() => null) ?? null,
    pricing_overrides: await engine.getConfig('pricing.overrides').catch(() => null) ?? null,
    // Built-in prices and default caps move with releases.
    gbrain_version: VERSION,
  };
  // An unreadable benchmark hashes as null (never matches a stored skip), so the
  // skill is re-admitted and fails on its own instead of throwing the phase.
  const fingerprint = (benchmarkPath: string): string => {
    let benchmarkSha8: string | null = null;
    try { benchmarkSha8 = sha8(fs.readFileSync(benchmarkPath, 'utf8')); } catch { /* re-admit */ }
    return JSON.stringify({ ...admission, benchmark_sha8: benchmarkSha8 });
  };

  // Walk skills dir; pick candidates with skillopt-benchmark.jsonl + stale last_run_at.
  const candidates = await collectCandidates(engine, skillsDir, staleDays, fingerprint);
  if (candidates.length === 0) {
    return {
      phase: 'skillopt',
      status: 'ok',
      duration_ms: Date.now() - start,
      summary: 'no stale skills with benchmarks; nothing to optimize',
      details: { skills_scanned: 0, candidates: 0, brain_wide_cap_usd: brainWideCap },
    };
  }

  const basePlan = await buildModelsPlan(engine, models);
  process.stderr.write(formatModelsBanner(basePlan));

  // Run per-skill. Each invocation gets its own per-skill cap; we track
  // cumulative cost across the cycle and bail when brain-wide cap hit.
  const results: SkillResult[] = [];
  let cumulativeCostUsd = 0;
  let skipped_brain_wide_cap = 0;
  let skipped_budget = 0;

  for (const c of candidates) {
    if (opts.signal?.aborted) break;
    if (cumulativeCostUsd >= brainWideCap) {
      skipped_brain_wide_cap += 1;
      results.push({ skill: c.name, outcome: 'skipped', cost_usd: 0, reason: 'brain_wide_cap_reached' });
      continue;
    }
    // Cap the per-skill spend at min(per_skill_cap, remaining_brain_wide).
    const remaining = brainWideCap - cumulativeCostUsd;
    const effectiveCap = Math.min(perSkillCap, remaining);

    try {
      const split = parseSplit('4:1:5');
      const skillOptOpts: SkillOptOpts = {
        engine,
        skillName: c.name,
        skillsDir,
        benchmarkPath: c.benchmarkPath,
        epochs: 1, // incremental nightly: ONE epoch per cycle
        batchSize: 4, // smaller batch for the nightly path
        lr: 4,
        lrSchedule: 'cosine',
        split,
        ...skillOptModelOpts(models),
        modelsBannerBaseline: basePlan,
        mode: 'patch',
        optimizerMode: 'one-shot-rewrite',
        dryRun: opts.dryRun ?? false,
        // Bundled-skill safety: dream-cycle NEVER auto-mutates bundled skills.
        // For bundled skills we set --no-mutate; the user reviews proposed.md
        // at their own cadence.
        noMutate: true, // ALL dream-cycle runs are no-mutate by default
        allowMutateBundled: false,
        bootstrapReviewed: false,
        json: true,
        maxCostUsd: effectiveCap,
        maxRuntimeMin: 10, // shorter wall-clock cap for the nightly path
        force: false,
      };
      const result = await runSkillOpt(skillOptOpts);
      const receipt = result.receipt;
      const spent = receipt.final_cost_usd ?? 0;
      cumulativeCostUsd += spent;
      results.push({
        skill: c.name,
        outcome: result.outcome,
        cost_usd: spent,
        ...(receipt.abort_reason ? { abort_reason: receipt.abort_reason } : {}),
        ...(receipt.abort_detail ? { abort_detail: receipt.abort_detail } : {}),
        ...(receipt.run_id ? { run_id: receipt.run_id } : {}),
        ...(receipt.remediation?.length ? { remediation: receipt.remediation } : {}),
      });
      // Persist last_run_at so we don't re-enter every cycle; an errored run
      // records last_error instead so it is retried (after the 24h gate).
      const stateKey = result.outcome === 'errored' ? 'last_error' : 'last_run';
      await engine.setConfig(`cycle.skillopt.${stateKey}.${c.name}`, String(Date.now()));
    } catch (err) {
      const msg = err instanceof Error ? err.message : String(err);
      if (err instanceof StructuredAgentError && errorCode(err.envelope.message) === 'reservation_exceeds_cap') {
        if (effectiveCap < perSkillCap) {
          skipped_brain_wide_cap += 1;
          results.push({ skill: c.name, outcome: 'skipped', cost_usd: 0, reason: 'brain_wide_cap_reached' });
        } else {
          skipped_budget += 1;
          results.push({ skill: c.name, outcome: 'skipped_budget', cost_usd: 0, reason: err.envelope.message,
            remediation: buildRemediation(['reservation_exceeds_cap']) });
          await engine.setConfig(`cycle.skillopt.last_skip.${c.name}`, fingerprint(c.benchmarkPath)).catch(() => {});
        }
        continue;
      }
      results.push({ skill: c.name, outcome: 'errored', cost_usd: 0, reason: msg });
      await engine.setConfig(`cycle.skillopt.last_error.${c.name}`, String(Date.now())).catch(() => {});
    }
  }

  const accepted = results.filter((r) => r.outcome === 'accepted').length;
  const noImprovement = results.filter((r) => r.outcome === 'no_improvement').length;
  const errored = results.filter((r) => r.outcome === 'errored').length;

  return {
    phase: 'skillopt',
    status: errored > 0 ? 'warn' : 'ok',
    duration_ms: Date.now() - start,
    summary: `optimized ${accepted}/${candidates.length} skills (${noImprovement} no-improvement, ${errored} errored, ${skipped_brain_wide_cap} skipped over brain-wide cap${skipped_budget > 0 ? `, ${skipped_budget} skipped: one call exceeds the per-skill cap` : ''})`,
    details: {
      skills_scanned: candidates.length,
      accepted,
      no_improvement: noImprovement,
      errored,
      skipped_brain_wide_cap,
      skipped_budget,
      cumulative_cost_usd: cumulativeCostUsd,
      brain_wide_cap_usd: brainWideCap,
      per_skill_cap_usd: perSkillCap,
      results,
    },
  };
}

/**
 * Walk skillsDir and return skills that have a benchmark file AND a stale
 * last_run_at (older than staleDays, or never run) AND no error within the
 * last 24h AND no budget skip under the current admission fingerprint.
 */
async function collectCandidates(
  engine: BrainEngine,
  skillsDir: string,
  staleDays: number,
  fingerprint: (benchmarkPath: string) => string,
): Promise<SkillCandidate[]> {
  const out: SkillCandidate[] = [];
  if (!fs.existsSync(skillsDir)) return out;
  const cutoffMs = Date.now() - staleDays * 86400 * 1000;
  for (const entry of fs.readdirSync(skillsDir)) {
    const skillDir = path.join(skillsDir, entry);
    if (!fs.statSync(skillDir).isDirectory()) continue;
    const benchPath = path.join(skillDir, 'skillopt-benchmark.jsonl');
    if (!fs.existsSync(benchPath)) continue;
    // Read last_run_at.
    let lastRunAt: number | null = null;
    try {
      const v = await engine.getConfig(`cycle.skillopt.last_run.${entry}`);
      if (v) lastRunAt = Number(v);
    } catch { /* fall through */ }
    if (lastRunAt !== null && lastRunAt >= cutoffMs) {
      continue; // ran recently; skip
    }
    let lastErrorAt: number | null = null;
    try {
      const v = await engine.getConfig(`cycle.skillopt.last_error.${entry}`);
      if (v) lastErrorAt = Number(v);
    } catch { /* fall through */ }
    if (lastErrorAt !== null && Date.now() - lastErrorAt < ERROR_RETRY_MS) {
      continue; // errored recently; retry after the 24h gate
    }
    const lastSkip = await engine.getConfig(`cycle.skillopt.last_skip.${entry}`).catch(() => null);
    if (lastSkip && !lastSkip.includes('"benchmark_sha8":null') && lastSkip === fingerprint(benchPath)) continue; // budget-skipped; wait for a config change
    out.push({ name: entry, benchmarkPath: benchPath, lastRunAt });
  }
  return out;
}

async function readNumericConfig(engine: BrainEngine, key: string, defaultValue: number): Promise<number> {
  try {
    const v = await engine.getConfig(key);
    if (v) {
      const n = Number(v);
      if (Number.isFinite(n) && n > 0) return n;
    }
  } catch { /* fall through */ }
  return defaultValue;
}