Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.4 KB
Raw Blame
// src/core/onboard/init-nudge.ts
// v0.41.18.0 (A4 + A18 + A20, T14). Post-initSchema summary that runs
// the 4 onboard checks against a 3-second wallclock budget and prints
// a one-line nudge if recommendations exist.
//
// Hard contract per A18: init MUST succeed even if the nudge crashes.
// Any throw in this module is caught + logged to stderr + suppressed.
// Per A20: the 3-second cap uses real cancellation via the AbortSignal
// extension on executeRaw (T5) — Promise.race against a timer was the
// codex #7 finding's wrong shape. Cancelled queries actually stop on
// Postgres; PGLite has a documented gap.
//
// Bypass: GBRAIN_NO_ONBOARD_NUDGE=1 short-circuits. Non-interactive callers
// (agents) get the same coaching as an [AGENT] block (agent contract F7).

import type { BrainEngine } from '../engine.ts';
import { writeCliNotices } from '../interop-notices.ts';
import { collectOnboardOpportunities, LINK_COVERAGE_MIN, TIMELINE_COVERAGE_MIN } from './mcp-onboarding.ts';

const NUDGE_BUDGET_MS = 3000;

/**
 * Post-initSchema nudge. Fail-open per A18.
 *
 * Returns silently when:
 *   - GBRAIN_NO_ONBOARD_NUDGE=1
 *   - All 4 onboard checks complete within 3s AND surface 0 recommendations
 *   - ANY error during check execution (logged to stderr, suppressed)
 *
 * Emits an `onboard_opportunities` coaching notice (stderr on a terminal,
 * an [AGENT] block on stdout for a non-interactive caller) when:
 *   - Recommendations exist within budget
 *   - Some checks ran but budget fired (partial-results path)
 */
export async function runInitNudge(engine: BrainEngine): Promise<void> {
  try {
    if (process.env.GBRAIN_NO_ONBOARD_NUDGE === '1') return;

    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), NUDGE_BUDGET_MS);

    const counts = await collectOnboardOpportunities(engine, controller.signal);
    clearTimeout(timer);

    const totalStale = counts.staleChunks ?? 0;
    const totalEntities = counts.entities ?? 0;
    const linkedCount = counts.linkedEntities ?? 0;
    const timelineCount = counts.timelineEntities ?? 0;
    const takesCount = counts.takes ?? 0;
    // -1 = the page-count probe failed: fail-open sentinel, treat as non-empty
    // so current behavior is preserved when the count is unknown.
    const totalPages = counts.pages ?? -1;
    const { checksRan, checksAttempted, partial } = counts;

    // A brand-new EMPTY brain has no "opportunities" — telling a fresh user
    // "0 takes" at the end of their first init is jargon-noise on the
    // activation surface. Suppress the ENTIRE nudge on empty (including the
    // partial-checks notice below).
    const brainEmpty = totalPages === 0;
    if (brainEmpty) return;

    // Aggregate: any non-zero metric triggers the nudge.
    const linkCoverage = totalEntities > 0 ? linkedCount / totalEntities : 1;
    const timelineCoverage = totalEntities > 0 ? timelineCount / totalEntities : 1;
    const hasRecommendations =
      totalStale > 0
      || (totalEntities > 0 && linkCoverage < LINK_COVERAGE_MIN)
      || (totalEntities > 0 && timelineCoverage < TIMELINE_COVERAGE_MIN)
      || takesCount === 0;
    if (!hasRecommendations && !partial) return;

    // Emit one-line nudge. Be terse — init is the activation surface.
    const parts: string[] = [];
    if (totalStale > 0) parts.push(`${totalStale} stale chunks`);
    if (totalEntities > 0 && linkCoverage < LINK_COVERAGE_MIN) {
      parts.push(`link coverage ${Math.round(linkCoverage * 100)}%`);
    }
    if (totalEntities > 0 && timelineCoverage < TIMELINE_COVERAGE_MIN) {
      parts.push(`timeline coverage ${Math.round(timelineCoverage * 100)}%`);
    }
    if (takesCount === 0) parts.push('0 takes');

    // Agent contract v1 (F7): a coaching notice on every surface — terminal
    // lines, an [AGENT] block for a non-interactive caller (no more silence
    // exactly when an agent runs init).
    const why = parts.length === 0
      ? `Init checks incomplete (${checksRan}/${checksAttempted}) — run 'gbrain onboard --check' for full recommendations.`
      : `Brain has opportunities: ${parts.join(', ')}. Run 'gbrain onboard --check' to see the plan.` +
        (partial ? ` (${checksRan}/${checksAttempted} checks complete; run gbrain onboard --check for full recommendations)` : '');
    writeCliNotices([{
      code: 'onboard_opportunities', kind: 'coaching', why,
      fix: { argv: ['gbrain', 'onboard', '--check'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Lists each recommendation with its command; read-only.' },
    }]);
  } catch (err) {
    // A18: NEVER crash init from the nudge. Log and continue.
    process.stderr.write(`[onboard] nudge skipped (${err instanceof Error ? err.message : String(err)})\n`);
  }
}

/**
 * Post-upgrade banner. Lighter than the init nudge — just highlights
 * that new onboard recommendations may exist. Fail-open identically.
 */
export async function runUpgradeBanner(_engine: BrainEngine): Promise<void> {
  try {
    if (process.env.GBRAIN_NO_ONBOARD_NUDGE === '1') return;
    writeCliNotices([{
      code: 'onboard_opportunities', kind: 'coaching',
      why: "Upgrade complete. Run 'gbrain onboard --check' to see if the new version surfaces any new opportunities.",
      fix: { argv: ['gbrain', 'onboard', '--check'], consent: [], actor: 'agent', requires_exclusive: false, why: 'Lists each recommendation with its command; read-only.' },
    }]);
  } catch {
    // A18 posture for symmetry.
  }
}