Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.8 KB
Raw Blame
/**
 * gbrain questions — pinned questions (standing answers kept current from
 * evidence). Every path dispatches through the trusted-local op layer
 * (handleToolCall, remote:false) so the CLI and the questions_* MCP tools
 * share one behavior.
 *
 *   gbrain questions pin "<question>" [--source <id>] [--prefix <slug-prefix>] [--entity <slug>] [--defer] [--wait-ms N]
 *   gbrain questions pin --id <id> [--publish]      activate (or re-pin) an existing pin
 *   gbrain questions list [--source <id>] [--include-archived]
 *   gbrain questions status <id>
 *   gbrain questions refresh <id> [--full] [--wait-ms N]
 *   gbrain questions unpin <id>
 * Every subcommand takes --json (the receipt). Exit 1 when the answer is
 * blocked (no key, budget, failed refresh, awaiting consent) or a refresh did
 * not publish.
 */
import type { BrainEngine } from '../core/engine.ts';
import { handleToolCall } from '../mcp/server.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { shellQuote } from '../core/agent-output.ts';
import type { QuestionReceipt } from '../core/questions/receipt.ts';

const HELP = [
  'gbrain questions — pinned questions: cited answers kept current from your notes',
  '',
  '  pin "<question>"   pin a question and get its first answer (paid model call)',
  '      --source <id>      evidence source (default: current source)',
  '      --prefix <p>       only pages under this slug prefix, e.g. projects/',
  '      --entity <slug>    the entity page the question is about (context_pack shows its answer)',
  '      --defer            pin without the first answer',
  '      --wait-ms N        max wait for the first answer (default 30000)',
  '  pin --id <id>      activate an inactive pin (made over MCP, or imported from dream.auto_think)',
  '      --publish          publish a draft-only pin',
  '  list               pins with freshness and blocked reason (--include-archived, --source <id>)',
  '  status <id>        the answer with per-sentence stale flags and the next action',
  '  refresh <id>       refresh now (--full recomputes; --wait-ms N)',
  '  unpin <id>         stop refreshing and archive the page',
  '',
  'Every subcommand takes --json. Docs: docs/guides/pinned-questions.md',
].join('\n');

function flag(args: string[], name: string): string | undefined {
  const i = args.indexOf(name);
  return i !== -1 ? args[i + 1] : undefined;
}

function positional(args: string[]): string | undefined {
  const valueFlags = new Set(['--source', '--prefix', '--entity', '--wait-ms', '--id', '--brain']);
  for (let i = 0; i < args.length; i++) {
    if (valueFlags.has(args[i])) { i++; continue; }
    if (args[i] === '--') return args[i + 1];
    if (!args[i].startsWith('--')) return args[i];
  }
  return undefined;
}

function waitMs(args: string[]): number | undefined {
  const raw = flag(args, '--wait-ms');
  return raw !== undefined && Number.isFinite(Number(raw)) ? Number(raw) : undefined;
}

function blocked(r: QuestionReceipt): boolean {
  return r.blocked_reason !== null || (r.refresh !== undefined && !['published', 'skipped'].includes(r.refresh.status));
}

function renderReceipt(r: QuestionReceipt, withAnswer: boolean): string {
  const lines = [`${r.id}  [${r.freshness}${r.state !== 'active' ? `, ${r.state}` : ''}${r.publish_mode === 'draft' ? ', draft' : ''}]`, `  Q: ${r.question}`];
  if (r.refresh) lines.push(`  refresh: ${r.refresh.status}${'blocked_reason' in r.refresh ? ` (${r.refresh.blocked_reason})` : ''}${'detail' in r.refresh ? ` — ${r.refresh.detail}` : ''}`);
  if (withAnswer && r.answer?.length) {
    for (const s of r.answer) lines.push(`  ${s.stale ? '[stale] ' : ''}${s.origin === 'owner' ? '(you) ' : ''}${s.text}`);
  } else if (withAnswer && r.answer_revision > 0) {
    lines.push('  (no answer sentences: the evidence did not answer it)');
  }
  lines.push(`  sentences: ${r.sentences.fresh} fresh, ${r.sentences.stale} stale${r.sentences.withheld ? `, ${r.sentences.withheld} withheld` : ''}; last refresh: ${r.last_refresh_at ?? 'never'}`);
  if (r.blocked_reason) lines.push(`  blocked: ${r.blocked_reason}`);
  if (r.fix) {
    const cmd = r.fix.argv ? shellQuote(r.fix.argv) : r.fix.mcp?.tool;
    lines.push(`  next: ${cmd}`, `        ${r.fix.why}`);
  }
  return lines.join('\n');
}

export async function runQuestions(engine: BrainEngine, args: string[]): Promise<void> {
  const sub = args[0];
  const rest = args.slice(1);
  if (!sub || sub === '--help' || sub === '-h' || rest.includes('--help') || rest.includes('-h')) {
    process.stdout.write(HELP + '\n');
    return;
  }
  const json = rest.includes('--json');
  const source = flag(rest, '--source');
  const out = (doc: unknown, text: string) => process.stdout.write((json ? JSON.stringify(doc, null, 2) : text) + '\n');

  if (sub === 'pin') {
    const id = flag(rest, '--id');
    const question = id ? undefined : positional(rest);
    if (!id && !question) {
      console.error('Usage: gbrain questions pin "<question>" [--source <id>] [--prefix <p>] [--entity <slug>]  |  gbrain questions pin --id <id>');
      process.exit(2);
    }
    const prefix = flag(rest, '--prefix');
    const entity = flag(rest, '--entity');
    const params: Record<string, unknown> = id ? { id } : {
      question,
      ...(source || prefix || entity ? { scope: { ...(source ? { source } : {}), ...(prefix ? { slug_prefix: prefix } : {}), ...(entity ? { entity } : {}) } } : {}),
    };
    if (rest.includes('--defer')) params.defer = true;
    if (rest.includes('--publish')) params.publish = true;
    const wait = waitMs(rest);
    if (wait !== undefined) params.wait_ms = wait;
    const result = await handleToolCall(engine, 'questions_pin', params) as { created: boolean; activated: boolean; receipt: QuestionReceipt };
    out({ ok: !blocked(result.receipt), ...result }, `${result.created ? 'Pinned' : result.activated ? 'Activated' : 'Already pinned'}: ${renderReceipt(result.receipt, true)}`);
    if (blocked(result.receipt)) setCliExitVerdict(1);
    return;
  }
  if (sub === 'list') {
    const result = await handleToolCall(engine, 'questions_list', { ...(source ? { source } : {}), ...(rest.includes('--include-archived') ? { include_archived: true } : {}) }) as {
      questions: QuestionReceipt[]; counts: Record<string, number>;
    };
    const c = result.counts;
    out({ ok: true, ...result }, result.questions.length === 0
      ? 'No pinned questions. Pin one: gbrain questions pin "<question>"'
      : [...result.questions.map(r => renderReceipt(r, false)), '', `${c.total} pinned: ${c.fresh} fresh, ${c.stale} stale, ${c.awaiting_refresh} awaiting refresh, ${c.blocked} blocked`].join('\n'));
    return;
  }
  if (sub === 'status' || sub === 'refresh' || sub === 'unpin') {
    const id = positional(rest);
    if (!id) {
      console.error(`Usage: gbrain questions ${sub} <id>   (ids: gbrain questions list)`);
      process.exit(2);
    }
    if (sub === 'status') {
      const r = await handleToolCall(engine, 'questions_status', { id }) as QuestionReceipt;
      out({ ok: !blocked(r), ...r }, renderReceipt(r, true));
      if (blocked(r)) setCliExitVerdict(1);
      return;
    }
    if (sub === 'refresh') {
      const wait = waitMs(rest);
      const r = await handleToolCall(engine, 'questions_refresh', { id, ...(rest.includes('--full') ? { full: true } : {}), ...(wait !== undefined ? { wait_ms: wait } : {}) }) as QuestionReceipt;
      out({ ok: !blocked(r), ...r }, renderReceipt(r, true));
      if (blocked(r)) setCliExitVerdict(1);
      return;
    }
    const result = await handleToolCall(engine, 'questions_unpin', { id }) as { unpinned: boolean; receipt: QuestionReceipt };
    out({ ok: true, ...result }, result.unpinned ? `Unpinned ${result.receipt.id}: refreshes stopped and its page is archived.` : `${result.receipt.id} was already unpinned.`);
    return;
  }
  console.error(`Unknown subcommand: ${sub} (try: gbrain questions --help)`);
  process.exit(2);
}