Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
17.4 KB
Raw Blame
/**
 * `gbrain init --json`'s first-run decision bundle (agent contract v1 D2,
 * spec G5): ONE `kind: 'ask'` notice whose `decisions[]` carry what the human
 * output relays through `[AGENT]` lines, plus one `user_message`. Init stays
 * non-blocking (exit 0); the agent relays the message and applies the chosen
 * options' argv.
 *
 * Decisions: `search_mode` (the picker's recommendation and cost matrix),
 * `writeback` (in effect `off`, recommended `salient`, offered on a personal brain whose
 * operator has not answered) and the
 * optional `skills_scaffold` (recommended skills missing from the detected
 * agent workspace; default skip), then `upkeep` (GBRA-438: the free upkeep
 * line, a setting in effect whose default `on` needs no answer; it rides a
 * bundle that has another entry and never opens one alone) and
 * `conversation_archive` (GST-2768: on, or offered on a shared brain; rides the
 * same way). Human output renders the same bundle
 * (`[AGENT]` block without a terminal, `Note` lines on one); it replaces
 * init's separate writeback ask and skills pointer. Extend
 * `buildInitFirstRunNotices` rather than adding another settings notice; the
 * one separate notice is `harness_wiring`, an install step the agent does.
 */
import { cliRenderContext, renderNotice, shellQuote, type Decision, type Notice } from '../core/agent-output.ts';
import { loadConfig, type GBrainConfig } from '../core/config.ts';
import type { BrainEngine } from '../core/engine.ts';
import { resolveGbrainBin } from '../core/gbrain-bin.ts';
import { configReadiness, embeddingEnablement, harnessWiringEntry } from '../core/readiness.ts';
import type { SearchMode } from '../core/search/mode.ts';
import { costMatrixSentence, OPENAI_COST_MATRIX_MODELS } from '../core/search/mode-advice.ts';
import type { McpSurface } from '../mcp/surface.ts';

export interface InitFirstRunInputs {
  /** The search mode the install-time picker applied and why; absent when `--search-mode` recorded the operator's choice. */
  searchMode?: { mode: SearchMode; reason: string };
  /** The config init saved; harness wiring is read from its config-plane readiness. */
  config?: GBrainConfig | null;
  /** True when the ambient-writeback ask applies (`writebackAskApplies`). */
  writeback?: boolean;
  /** Recommended skills missing from the agent workspace (`initSkillsScaffold`). */
  skillsScaffold?: { missing: string[]; argv: string[] } | null;
  /** `gbrain init --surface`: the surface the harness registration pins (default REGISTRATION_SURFACE). */
  surface?: McpSurface;
  /** GBRA-438: the upkeep line, relayed with the block as a setting in effect; `embedding` says the capped embedding step applies. */
  upkeep?: { embedding: boolean };
  /** GST-2768: the conversation archive line, a setting in effect: on (a personal brain) or offered (a shared one). */
  archive?: { state: 'on' | 'offered'; embedding: boolean };
}

/** GBRA-438: what runs on its own, stated as a setting in effect (the plan's wording; the keyed form names the one capped paid step). */
export function upkeepLine(embedding: boolean): string {
  return "Upkeep: free upkeep runs on its own while your agent's gbrain session is open. "
    + (embedding
      ? 'Nothing is deleted without you, and the only paid step is embedding new text, capped at $1 a day (maintenance.embed_daily_usd). '
      : 'Nothing is deleted or paid for without you. ')
    + 'Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule.';
}

/** GST-2768: the conversation archive as a setting in effect: what it keeps, where, what leaves the machine, how to change it. */
export function archiveLine(state: 'on' | 'offered', embedding: boolean): string {
  if (state === 'offered') {
    return 'Conversation archive: off on this shared brain. Turn it on with gbrain transcripts archive on: one redacted page per conversation per day from '
      + 'your agent sessions, kept to the owner member, in the conversations source.';
  }
  return 'Conversation archive: on. gbrain keeps one redacted page per conversation per day from your agent sessions (Claude Code, Codex, OpenClaw, Hermes, Grok) '
    + 'in the conversations source, written by the maintenance pass. '
    + (embedding
      ? 'New days are embedded like any new page (unattended upkeep caps that at maintenance.embed_daily_usd); older history is keyword-only until you approve its cost (gbrain embed --held --dry-run). '
      : 'Without an embedding key nothing leaves this machine. ')
    + 'Turn off: gbrain transcripts archive off.';
}

function archiveDecision(state: 'on' | 'offered', embedding: boolean): Decision {
  return {
    id: 'conversation_archive',
    question: archiveLine(state, embedding),
    options: [
      { id: 'on', label: state === 'on' ? 'Keep the conversation archive on (in effect now)' : 'Turn the conversation archive on', ...(state === 'on' ? {} : { argv: ['gbrain', 'transcripts', 'archive', 'on'] }) },
      { id: 'off', label: state === 'on' ? 'Turn the conversation archive off' : 'Keep it off (in effect now)', ...(state === 'on' ? { argv: ['gbrain', 'transcripts', 'archive', 'off'] } : {}) },
    ],
    default: state === 'on' ? 'on' : 'off',
    default_reason: state === 'on'
      ? 'In effect now: on by default on a personal brain; nothing needs an answer.'
      : 'A shared brain is only offered the archive; it stays off until the owner turns it on.',
  };
}

function upkeepDecision(embedding: boolean): Decision {
  return {
    id: 'upkeep',
    question: upkeepLine(embedding),
    options: [
      { id: 'on', label: 'Keep free upkeep on (in effect now)' },
      { id: 'off', label: 'Turn free upkeep off', argv: ['gbrain', 'config', 'set', 'maintenance.auto', 'false'] },
    ],
    default: 'on',
    default_reason: 'In effect now: the agent\'s gbrain serve runs the free upkeep tier while idle; nothing needs an answer.',
  };
}

function searchModeDecision(applied: { mode: SearchMode; reason: string }): Decision {
  const modes: SearchMode[] = ['conservative', 'balanced', 'tokenmax'];
  return {
    id: 'search_mode',
    question: `Which search mode should this brain use? ${costMatrixSentence()}`,
    options: modes.map(m => ({ id: m, label: m === applied.mode ? `${m} (applied)` : m, argv: ['gbrain', 'config', 'set', 'search.mode', m] })),
    default: applied.mode,
    default_reason: applied.reason,
  };
}

/**
 * Connecting gbrain to the agent is an install step, never a setting waiting
 * for the user's OK (Garry's G, GST-2719): its own notice, so an agent that
 * relays the settings has already connected memory.
 */
function harnessWiringNotice(config: GBrainConfig, surface?: McpSurface): Notice | null {
  const entry = configReadiness(config, { transport: 'cli', ...(surface ? { surface } : {}) }).entries.find(e => e.capability === 'harness_wiring');
  if (!entry?.fix || entry.state === 'ok') return null;
  const fix = entry.fix;
  const registration = !!fix.argv && fix.actor === 'agent' && fix.consent.length === 1 && fix.consent[0] === 'persistent_install';
  if (!registration) {
    return {
      code: 'harness_wiring',
      kind: 'info',
      why: `gbrain is not connected to an agent here, and this step is not a command the agent runs by itself; say so in the reply that reports the install, without waiting on it. ${fix.user_message ?? ''} ${fix.why ?? ''}`.trim(),
      fix,
    };
  }
  return {
    code: 'harness_wiring',
    kind: 'info',
    why: 'Connect gbrain to the agent now, as part of this install: it is an install step, not a setting, so do it before reporting the install. The fix names the command for this host.',
    fix: { ...fix, actor: 'agent', consent: [], user_message: undefined },
  };
}

function writebackDecision(): Decision {
  const set = (mode: string) => ['gbrain', 'config', 'set', 'memory.auto_writeback', mode];
  return {
    id: 'writeback',
    question: 'Should agents save important facts the user states (preferences, decisions, commitments) automatically, with provenance? '
      + 'Saved facts are readable by agents connected to this brain; transient facts expire. Off any time with `gbrain config set memory.auto_writeback off`.',
    options: [
      { id: 'salient', label: 'Save durable facts the user states directly (recommended)', argv: set('salient') },
      { id: 'all', label: 'Every direct factual statement (more low-value facts, more extraction spend)', argv: set('all') },
      { id: 'off', label: 'Save only what the user explicitly asks to remember (records the answer)', argv: set('off') },
    ],
    default: 'off',
    default_reason: 'In effect now: agents save only what the user asks them to remember. salient is recommended for a personal brain; it is opt-in, so it turns on only when the user picks it.',
  };
}

function skillsScaffoldDecision(scaffold: { missing: string[]; argv: string[] }): Decision {
  const preview = scaffold.missing.slice(0, 4).join(', ') + (scaffold.missing.length > 4 ? ', …' : '');
  return {
    id: 'skills_scaffold',
    question: `Install ${scaffold.missing.length} recommended gbrain skill(s) into the agent workspace (${preview})? Optional; \`gbrain advisor\` lists what each does.`,
    options: [
      { id: 'skip', label: 'Skip for now.' },
      { id: 'scaffold', label: 'Scaffold the recommended skills into the workspace.', argv: scaffold.argv },
    ],
    default: 'skip',
    default_reason: 'Optional: the brain works without them; scaffolding writes files into the user\'s workspace.',
  };
}

/** The bundle: empty when there is nothing to decide. */
export function buildInitFirstRunNotices(inputs: InitFirstRunInputs): Notice[] {
  const decisions: Decision[] = [];
  if (inputs.searchMode) decisions.push(searchModeDecision(inputs.searchMode));
  if (inputs.writeback) decisions.push(writebackDecision());
  if (inputs.skillsScaffold?.missing.length) decisions.push(skillsScaffoldDecision(inputs.skillsScaffold));
  const wiring = inputs.config ? harnessWiringNotice(inputs.config, inputs.surface) : null;
  if (decisions.length === 0 && !(wiring && inputs.upkeep)) return wiring ? [wiring] : [];
  if (inputs.upkeep) decisions.push(upkeepDecision(inputs.upkeep.embedding));
  if (inputs.archive) decisions.push(archiveDecision(inputs.archive.state, inputs.archive.embedding));
  const searchMode = decisions.find(d => d.id === 'search_mode');
  const upkeep = decisions.find(d => d.id === 'upkeep');
  const archive = decisions.find(d => d.id === 'conversation_archive');
  const inEffect = [
    ...(searchMode ? [`search mode ${searchMode.default}`] : []),
    ...(decisions.some(d => d.id === 'writeback') ? [WRITEBACK_IN_EFFECT] : []),
  ];
  return [...(wiring ? [wiring] : []), {
    code: 'first_run_decisions',
    kind: 'ask',
    why: 'The brain is ready and these first-run settings are in effect as listed; none blocks memory. '
      + 'Relay them once, in the reply that reports the install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. '
      + 'When the user picks an option, run its command. Nothing paid turns on from these settings without a key the user supplied.',
    user_message: `gbrain is installed.${inEffect.length ? ` In effect: ${inEffect.join('; ')}.` : ''}${upkeep ? ` ${upkeep.question}` : ''}${archive ? ` ${archive.question}` : ''}${searchMode ? ` ${costMatrixSentence()}` : ''} Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.`,
    decisions,
  }];
}

const WRITEBACK_IN_EFFECT = 'agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance)';

/**
 * `gbrain setup <harness>`'s form of init's bundle (read from `init --json`).
 * Setup has already wired the harness, so `harness_wiring` is dropped, and
 * the rest is framed as settings in effect that the user can change at any
 * time: the agent relays them in the reply that reports the install instead
 * of ending it on a question whose answer needs another turn (Cat 41 wave 2).
 * Open decisions keep returning in later sessions until answered or muted.
 * The Report back (Wakeshift) row states whether gbrain wakes the agent's
 * conversation when a job finishes (`opts.reportBack`: published) and the
 * one command that flips it.
 */
export function setupFirstRunNotices(initNotices: readonly unknown[], harness: string, opts: { reportBack?: boolean } = {}): Notice[] {
  const bundle = initNotices.find((n): n is Notice => (n as Notice | null)?.code === 'first_run_decisions');
  const matrix = costMatrixSentence(harness === 'Codex' ? OPENAI_COST_MATRIX_MODELS : undefined);
  const decisions = (bundle?.decisions ?? []).filter(d => d.id !== 'harness_wiring')
    .map(d => (d.id === 'search_mode' ? { ...d, question: `Which search mode should this brain use? ${matrix}` } : d));
  if (decisions.length === 0) return [];
  const searchMode = decisions.find(d => d.id === 'search_mode');
  const upkeep = decisions.find(d => d.id === 'upkeep');
  const archive = decisions.find(d => d.id === 'conversation_archive');
  const inEffect = [
    ...(searchMode ? [`search mode ${searchMode.default}`] : []),
    ...(decisions.some(d => d.id === 'writeback') ? [WRITEBACK_IN_EFFECT] : []),
  ];
  if (inEffect.length === 0 && !upkeep && !archive) return [];
  const reportBack = opts.reportBack
    ? 'Report back (Wakeshift): on. gbrain wakeshift disable turns it off.'
    : 'Report back (Wakeshift): off. gbrain wakeshift enable turns it on.';
  return [{
    code: 'first_run_decisions',
    kind: 'ask',
    why: `Setup is complete: the brain is ready and ${harness} is wired, so memory works now. These first-run settings are in effect as listed; none blocks memory or needs a new session to answer. `
      + 'Relay them once, in the reply that reports this install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. '
      + 'When the user picks an option, run its command. Automatic saving (`writeback`) is separate from setup\'s capture decision (Stop/SessionEnd hooks); while unanswered it comes back in a later session until the user answers or mutes it.',
    user_message: `gbrain is set up and ${harness} is wired, so memory works now.${inEffect.length ? ` In effect: ${inEffect.join('; ')}.` : ''} ${reportBack}${upkeep ? ` ${upkeep.question}` : ''}${archive ? ` ${archive.question}` : ''}${searchMode ? ` ${matrix}` : ''} Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.`,
    decisions,
  }];
}

/**
 * The deferred-setup line init prints for `--no-embedding`: the same enable
 * command readiness gives doctor, embed and MCP (A7 `embeddingEnablement`:
 * resolved datastore, a provider that fits, pages and facts kept).
 */
export function deferredEmbeddingHint(cfg: GBrainConfig): string {
  const enable = embeddingEnablement(cfg);
  const step = enable.argv ? shellQuote(enable.argv) : 'gbrain doctor --only embeddings --json';
  return `  --no-embedding: deferred setup — enable later with \`${step}\` (setting embedding_model through \`gbrain config set\` is refused by design)`;
}

/** init's bundle for this brain: reads the writeback gate and the agent workspace's missing skills. */
export async function firstRunBundle(engine: BrainEngine, searchMode: { mode: SearchMode; reason: string } | undefined, surface?: McpSurface): Promise<Notice[]> {
  const { writebackAskApplies } = await import('../core/onboard/writeback-nudge.ts');
  const { initSkillsScaffold } = await import('../core/skillpack/post-install-advisory.ts');
  const { isAvailable } = await import('../core/ai/gateway.ts');
  let embedding = false;
  try { embedding = isAvailable('embedding'); } catch { /* gateway not configured: keyless */ }
  const { resolveArchiveEnabled } = await import('../core/transcripts/archive-default.ts');
  const archive = await resolveArchiveEnabled(engine, { config: loadConfig() }).catch(() => null);
  const archiveState = archive?.enabled ? 'on' as const : archive?.offered ? 'offered' as const : null;
  return buildInitFirstRunNotices({
    searchMode, config: loadConfig(), writeback: await writebackAskApplies(engine), skillsScaffold: initSkillsScaffold(), surface, upkeep: { embedding },
    ...(archiveState ? { archive: { state: archiveState, embedding } } : {}),
  });
}

/** D2/G5: the bundle rendered into init's --json document (`notices`, empty → omitted). */
export function firstRunJson(bundle: Notice[]): { notices?: unknown[]; contract_version: 1 } {
  const notices = bundle.map(n => renderNotice(n, cliRenderContext()));
  return { ...(notices.length ? { notices } : {}), contract_version: 1 };
}

/**
 * The harness registration line for init's quickstart: the readiness
 * `harness_wiring` fix (absolute binary, `--surface starter --advertise verbs`
 * unless `gbrain init --surface` names another) for the detected harness, else the
 * Claude Code registration built the same way. Null when the gbrain binary
 * has no absolute path (never registered bare).
 */
export function harnessRegistrationCommand(surface?: McpSurface): string | null {
  const cfg = loadConfig();
  const detected = cfg ? configReadiness(cfg, { transport: 'cli', ...(surface ? { surface } : {}) }).entries.find(e => e.capability === 'harness_wiring')?.fix : undefined;
  if (detected?.argv) return shellQuote(detected.argv);
  const claude = harnessWiringEntry({ transport: 'cli', harnesses: ['claude-code'], lockOwner: null, gbrainBin: resolveGbrainBin(), ...(surface ? { surface } : {}) }).fix;
  return claude?.argv ? shellQuote(claude.argv) : null;
}