Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain facts relink` (#5836): link facts saved without an entity to the
* entity they are about. Trusted local CLI only; the work lives in
* src/core/facts/relink.ts and src/core/facts/relink-publish.ts.
*/
import type { BrainEngine } from '../core/engine.ts';
import type { GBrainConfig } from '../core/config.ts';
import { RELINK_DEFAULT_LIMIT, RELINK_DEFAULT_MAX_USD, runFactsRelink, type RelinkOptions, type RelinkReport } from '../core/facts/relink.ts';
import { RELINK_REASONS, type RelinkReason } from '../core/facts/relink-reasons.ts';
import { CONVERSATION_RELINK_PAGES, runConversationRelink, type ConversationRelinkReport } from '../core/facts/conversation-relink.ts';
import { DEFAULT_MAX_RESUBMITS, FACTS_ABSORB_RETRY_MAX_KEY, factsRetryDeadCommand, readDeadFactsAbsorbRetry, updateDeadFactsAbsorbKeys } from '../core/facts/dead-absorb-retry.ts';
export function factsHelpText(): string {
return `Usage: gbrain facts <subcommand>
Subcommands:
relink Link facts saved without an entity to the person, company or
project they are about, onto that entity page's ## Facts fence.
retry-dead Show or reset the retry set of dead page-write facts-absorb jobs.
gbrain facts relink [flags]
--source <id> Source to repair (default: the resolved source)
--dry-run Show what would link; writes nothing, calls no model
--limit <n> Facts to examine this run (default ${RELINK_DEFAULT_LIMIT})
--after-id <n> Start after this fact id (the printed continuation point)
--since <ISO date> Only facts created on or after this date
--no-llm Free tiers only (recorded page, unique entity mention)
--max-usd <n|off> Cap for the model tier (default ${RELINK_DEFAULT_MAX_USD.toFixed(2)}); alias --max-cost-usd
--retry-model Ask the model again about facts it already judged
--include-private Also send private facts to the model tier
--no-conflict-queue Do not queue linked facts for the conflict sweep
--examples <n> Example facts per outcome (default 3)
--json Machine-readable report (schema_version ${1})
gbrain facts relink --conversation [--unbacked] [--source <id>] [--slugs <a,b>] [--dry-run] [--json]
Link the conversation extractor's facts saved without an entity (plain
relink never examines them), free only: a fact naming exactly one entity
page in full is linked, one write per page. Without --slugs, the
${CONVERSATION_RELINK_PAGES} pages with the most untried unlinked facts. Facts it cannot
resolve are recorded, and the report prints the paid re-extraction for
their pages. --unbacked moves facts saved under a name tag (a full name
with no page, facts.unbacked_entity_keys) onto the page that name now
resolves to (exact slug, unique basename, unique alias or the same name);
preview with --dry-run first.
Relink never creates pages and never supersedes a fact. Exact duplicates are
retired (expired, kept in history). Linked facts are queued for the System One
conflict sweep when that slot is on. Free tiers cost nothing; the model tier
uses facts.extraction_model and stops at --max-usd.
gbrain facts retry-dead [--list] [--json]
gbrain facts retry-dead --reset <key>|--all [--json]
gbrain facts retry-dead --clear <key>|--all [--json]
A put_page's facts-absorb job that died on a provider or configuration
failure is re-submitted by the next maintenance pass (the facts_drain
phase) once extraction is servable again, at most
${FACTS_ABSORB_RETRY_MAX_KEY} times per job (default ${DEFAULT_MAX_RESUBMITS}; 0 disables) and at most
once an hour. --list shows the set: pending, exhausted (at the limit),
cleared and not retryable (a deterministic failure). --reset lets the next
pass re-submit a key again (naming a not-retryable job's key, after its
cause is fixed, adds it); --clear stops re-submitting a key. Keys are the
jobs' idempotency keys (facts-absorb:write:<request id>). Each re-submitted
job is one paid extraction call when it runs.`;
}
interface ParsedArgs { opts: Omit<RelinkOptions, 'config'>; json: boolean; error?: string }
function parseRelinkArgs(args: string[], sourceId: string): ParsedArgs {
const opts: Omit<RelinkOptions, 'config'> = { sourceId, maxUsd: RELINK_DEFAULT_MAX_USD };
let json = false;
const value = (i: number, flag: string): string => {
const v = args[i + 1];
if (v === undefined || v.startsWith('--')) throw new Error(`${flag} requires a value`);
return v;
};
try {
for (let i = 0; i < args.length; i++) {
const a = args[i]!;
if (a === '--json') json = true;
else if (a === '--dry-run') opts.dryRun = true;
else if (a === '--no-llm') opts.llm = false;
else if (a === '--retry-model') opts.retryModel = true;
else if (a === '--include-private') opts.includePrivate = true;
else if (a === '--no-conflict-queue') opts.conflictQueue = false;
else if (a === '--source') { opts.sourceId = value(i, a); i++; }
else if (a === '--limit' || a === '--after-id' || a === '--examples') {
const n = Number(value(i, a));
if (!Number.isSafeInteger(n) || n < (a === '--after-id' || a === '--examples' ? 0 : 1)) throw new Error(`${a} must be a whole number`);
if (a === '--limit') opts.limit = n; else if (a === '--after-id') opts.afterId = n; else opts.examples = n;
i++;
} else if (a === '--since') {
const raw = value(i, a);
const d = new Date(raw);
if (!/^\d{4}-\d{2}-\d{2}/.test(raw) || Number.isNaN(d.getTime())) throw new Error('--since takes an ISO 8601 date (e.g. 2026-09-01); use --after-id for a fact id');
opts.since = d;
i++;
} else if (a === '--max-usd' || a === '--max-cost-usd') {
const raw = value(i, a);
if (/^(off|unlimited|none)$/i.test(raw)) opts.maxUsd = null;
else {
const n = Number(raw);
if (!Number.isFinite(n) || n < 0) throw new Error(`${a} takes a dollar amount or off`);
opts.maxUsd = n;
}
i++;
} else throw new Error(`unknown flag ${a}`);
}
} catch (err) {
return { opts, json, error: err instanceof Error ? err.message : String(err) };
}
return { opts, json };
}
function continuation(report: RelinkReport, args: string[]): string | null {
if (!report.has_more || report.next_after_id === null) return null;
const kept: string[] = [];
for (let i = 0; i < args.length; i++) {
if (args[i] === '--after-id') { i++; continue; }
kept.push(args[i]!);
}
return `gbrain facts relink ${[...kept, '--after-id', String(report.next_after_id)].join(' ')}`;
}
export function formatRelinkReport(report: RelinkReport, args: string[]): string {
const lines: string[] = [];
const t = report.linked_by_tier;
lines.push(`${report.dry_run ? 'DRY RUN: would link' : 'Linked'} ${report.linked} of ${report.scanned} unlinked fact(s) in source ${report.source_id}` +
` (page ${t.page}, mention ${t.mention}, model ${t.model}); ${report.deduped} exact duplicate(s) retired.`);
if (!report.dry_run && report.linked) {
lines.push(`Conflict sweep: ${report.queued_for_conflict} queued, ${report.eligible_for_conflict} eligible (have an embedding).`);
}
if (report.provider) {
const cost = report.estimated_model_cost_usd == null ? 'unknown price' : `est. $${report.estimated_model_cost_usd.toFixed(4)}`;
lines.push(`Model tier: ${report.facts_sent_to_model} fact(s) ${report.dry_run ? 'would go' : 'sent'} to ${report.provider} (${cost}` +
`${report.dry_run ? '' : `, spent $${report.spend_usd.toFixed(4)}`}).` +
(report.private_excluded_from_model ? ` ${report.private_excluded_from_model} private fact(s) held back (--include-private).` : ''));
}
const skipped = Object.entries(report.skipped) as Array<[RelinkReason, number]>;
if (skipped.length) {
lines.push('Not linked:');
for (const [reason, n] of skipped.sort((a, b) => b[1] - a[1])) lines.push(` ${reason}: ${n}. ${RELINK_REASONS[reason].fix}`);
}
if (report.fence_owned) lines.push(` fence_owned: ${report.fence_owned} (not examined). ${RELINK_REASONS.fence_owned.fix}`);
for (const [outcome, list] of Object.entries(report.examples)) {
lines.push(`Examples (${outcome}):`);
for (const e of list) lines.push(` #${e.id} ${e.fact}${e.target ? ` -> ${e.target}` : ''}`);
}
if (report.stopped) lines.push(`Stopped early: ${report.stopped}.`);
const next = continuation(report, args);
if (next) lines.push(`More unlinked facts remain. Continue with:\n ${next}`);
else if (report.dry_run && report.linked) lines.push(`Apply with:\n gbrain facts relink ${args.filter(a => a !== '--dry-run').join(' ')}`.trimEnd());
return lines.join('\n');
}
export function formatConversationRelinkReport(r: ConversationRelinkReport, args: string[]): string {
const lines = [`${r.dry_run ? 'DRY RUN: would link' : 'Linked'} ${r.linked} conversation fact(s) on ${r.pages.length} page(s) in source ${r.source_id}`
+ ` (${r.unbacked ? 'name tags moved onto their page' : 'mention tier'}, no model call); ${r.unresolved} ${r.unbacked ? 'still under a name tag with no page' : 'unresolved'}`
+ `${r.changed ? `; ${r.changed} changed before the write (run again)` : ''}.`];
if (r.not_user_attributed) lines.push(` not_user_attributed: ${r.not_user_attributed}. ${RELINK_REASONS.not_user_attributed.fix}`);
for (const p of r.pages) lines.push(` ${p.slug}: ${p.linked} linked, ${p.unresolved} unresolved`);
if (r.dry_run && r.linked) lines.push(`Apply with:\n gbrain facts relink ${args.filter(a => a !== '--dry-run').join(' ')}`);
if (r.reextract_slugs.length) {
const base = `gbrain extract-conversation-facts --source-id ${r.source_id} --slugs ${r.reextract_slugs.join(',')} --force`;
lines.push(`No entity could be proven for ${r.unresolved} fact(s). Re-extraction calls the fact model again (paid); preview, then run with the amount the user approves:\n ${base} --dry-run\n ${base} --max-cost-usd <N>`);
}
return lines.join('\n');
}
/** `--conversation` flags: --unbacked, --source, --slugs, --dry-run, --json; anything else is a usage error. */
async function runConversation(engine: BrainEngine, args: string[], config: GBrainConfig, sourceId: string): Promise<number> {
const opts: { sourceId: string; slugs?: string[]; dryRun?: boolean; unbacked?: boolean } = { sourceId };
let json = false;
for (let i = 0; i < args.length; i++) {
const a = args[i]!;
const v = args[i + 1];
if (a === '--conversation') continue;
if (a === '--json') json = true;
else if (a === '--dry-run') opts.dryRun = true;
else if (a === '--unbacked') opts.unbacked = true;
else if ((a === '--source' || a === '--slugs') && v !== undefined && !v.startsWith('--')) {
if (a === '--source') opts.sourceId = v; else opts.slugs = v.split(',').map(s => s.trim()).filter(Boolean);
i++;
} else {
console.error(`gbrain facts relink --conversation: ${a === '--source' || a === '--slugs' ? `${a} requires a value` : `unknown flag ${a} (takes --unbacked, --source, --slugs, --dry-run, --json)`}`);
return 1;
}
}
const report = await runConversationRelink(engine, config, opts);
console.log(json ? JSON.stringify(report, null, 2) : formatConversationRelinkReport(report, args));
return 0;
}
/** C-9: the dead facts-absorb retry set (src/core/facts/dead-absorb-retry.ts). Exit 1 on a usage error. */
async function runRetryDead(engine: BrainEngine, args: string[]): Promise<number> {
if (args.includes('--help') || args.includes('-h')) { console.log(factsHelpText()); return 0; }
const json = args.includes('--json');
const action = args.includes('--reset') ? 'reset' : args.includes('--clear') ? 'clear' : null;
if (args.includes('--reset') && args.includes('--clear')) { console.error('gbrain facts retry-dead: pass one of --reset or --clear.'); return 1; }
if (!action) {
const status = await readDeadFactsAbsorbRetry(engine);
if (json) { console.log(JSON.stringify(status, null, 2)); return 0; }
console.log(`Dead facts-absorb retry set (limit ${status.max_resubmits} re-submit(s) per job${status.max_resubmits === 0 ? ', disabled' : ''}):`);
console.log(` pending ${status.pending}, exhausted ${status.exhausted.length}, cleared ${status.cleared}, not retryable ${status.not_retryable.length}${status.waiting_on ? ` (waiting on ${status.waiting_on})` : ''}`);
for (const e of status.exhausted) console.log(` exhausted job ${e.job_id} ${e.slug ?? ''} after ${e.resubmits} re-submit(s); reset: ${factsRetryDeadCommand('--reset', e.key)}`);
for (const e of status.not_retryable.slice(0, 20)) console.log(` not retryable job ${e.job_id} ${e.slug ?? ''}: fix the cause in its error (gbrain jobs get ${e.job_id}), then gbrain jobs retry ${e.job_id}`);
return 0;
}
const flag = args.indexOf(`--${action}`);
const target = args[flag + 1];
const all = args.includes('--all');
if (!all && (!target || target.startsWith('--'))) { console.error(`gbrain facts retry-dead --${action} needs a key (facts-absorb:write:<request id>) or --all; gbrain facts retry-dead --list shows them.`); return 1; }
const changed = await updateDeadFactsAbsorbKeys(engine, action, all ? 'all' : [target!]);
if (json) console.log(JSON.stringify({ status: action, keys: changed }, null, 2));
else if (changed.length === 0) console.log(`No dead facts-absorb job matches ${all ? '--all' : target}; gbrain facts retry-dead --list shows the set.`);
else console.log(action === 'reset'
? `Reset ${changed.length} key(s); the next maintenance pass may re-submit them (one paid extraction call each).`
: `Cleared ${changed.length} key(s); they stay dead and are not re-submitted again.`);
return 0;
}
/** Exit code: 0 for complete and partial runs (limit or budget), 1 for usage errors. */
export async function runFactsCommand(engine: BrainEngine, args: string[], config: GBrainConfig, sourceId: string): Promise<number> {
const sub = args[0];
if (!sub || sub === '--help' || sub === '-h') {
console.log(factsHelpText());
return 0;
}
if (sub === 'retry-dead') return runRetryDead(engine, args.slice(1));
if (sub !== 'relink') {
console.error(`gbrain facts: unknown subcommand ${sub}\n\n${factsHelpText()}`);
return 1;
}
const rest = args.slice(1);
if (rest.includes('--help') || rest.includes('-h')) {
console.log(factsHelpText());
return 0;
}
if (rest.includes('--conversation')) return runConversation(engine, rest, config, sourceId);
const parsed = parseRelinkArgs(rest, sourceId);
if (parsed.error) {
console.error(`gbrain facts relink: ${parsed.error}`);
return 1;
}
const isTty = process.stderr.isTTY === true;
const report = await runFactsRelink(engine, {
...parsed.opts, config,
onModelStart: line => process.stderr.write(`[facts relink] ${line}\n`),
onProgress: isTty ? (done, total) => { if (done === total || done % 100 === 0) process.stderr.write(`\r[facts relink] free tiers ${done}/${total}`); if (done === total) process.stderr.write('\n'); } : undefined,
});
console.log(parsed.json ? JSON.stringify({ ...report, next_command: continuation(report, rest) }, null, 2) : formatRelinkReport(report, rest));
return 0;
}