Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
#!/usr/bin/env bun
/**
* derive-starter-ops.ts — propose the STARTER_OPS daily-driver slice from
* production `mcp_request_log` usage (amendment 23 + D12).
*
* Run: bun run scripts/derive-starter-ops.ts [--days N] [--target N]
*
* Reads the active brain (loadConfig → engine) through the shared usage
* reader (src/core/mcp-usage.ts — the same hygiene rules as the E4 CLI and
* the E3 advisor drift check: JSON-RPC method rows and 'surface_change'
* audit rows dropped, the legacy 'tools/call:<name>' prefix stripped),
* excludes automation-shaped clients (D12: >90% context_pack/delta boundary
* calls), and ranks ops by CLIENT COUNT — the union of per-client
* DISTINCT-op sets, never raw call volume, so one chatty client cannot
* define the starter set.
*
* PRINTS a proposed block for a human to paste into src/mcp/surface.ts
* (replacing FALLBACK_DAILY_OPS). It NEVER edits files. The always-included
* slices (VERB_NAMES spread + whoami + request_tools + the agent lane) are
* composed in surface.ts itself and excluded from the proposal.
*
* A window that reaches back past pruned request-log history (retention,
* src/core/mcp-request-log-retention.ts) is refused: exit 1, the truncation
* note on stderr naming the --days that is complete.
*
* Caveats printed with the proposal:
* - HTTP clients only (stdio never writes mcp_request_log).
* - BRAIN_TOOL_ALLOWLIST cross-check (D12): allowlist members missing from
* the derived set are listed — dropping one strands subagent parity.
* - test/mcp-surface.test.ts pins membership + monotonicity
* (verbs ⊆ starter ⊆ full); run it after pasting.
*/
import { loadConfig, toEngineConfig } from '../src/core/config.ts';
import { createEngine } from '../src/core/engine-factory.ts';
import { readClientOpUsageWithCoverage, truncatedWindowNote, MCP_USAGE_DEFAULT_WINDOW_DAYS, type ClientOpUsage } from '../src/core/mcp-usage.ts';
import { operations } from '../src/core/operations.ts';
import { ALWAYS_INCLUDED_STARTER_OPS } from '../src/mcp/surface.ts';
import { BRAIN_TOOL_ALLOWLIST } from '../src/core/minions/tools/brain-allowlist.ts';
/** Ops surface.ts always includes regardless of derivation (shared constant). */
const ALWAYS_INCLUDED = ALWAYS_INCLUDED_STARTER_OPS;
/**
* Default `--target` for this usage-driven recommendation tool (a tuning knob,
* not the shipped surface — the committed STARTER_OPS set is ~26 ops).
*/
const DEFAULT_TARGET_SIZE = 20;
function parseArgs(argv: string[]): { days: number; target: number } {
let days = MCP_USAGE_DEFAULT_WINDOW_DAYS;
let target = DEFAULT_TARGET_SIZE;
for (let i = 0; i < argv.length; i++) {
if (argv[i] === '--days') {
days = Number(argv[++i]);
if (!Number.isInteger(days) || days < 1 || days > 3650) {
console.error('--days must be an integer between 1 and 3650');
process.exit(1);
}
} else if (argv[i] === '--target') {
target = Number(argv[++i]);
if (!Number.isInteger(target) || target < ALWAYS_INCLUDED.size) {
console.error(`--target must be an integer >= ${ALWAYS_INCLUDED.size} (the always-included slice)`);
process.exit(1);
}
} else {
console.error(`Unknown flag: ${argv[i]}`);
console.error('Usage: bun run scripts/derive-starter-ops.ts [--days N] [--target N]');
process.exit(1);
}
}
return { days, target };
}
const { days, target } = parseArgs(process.argv.slice(2));
const config = loadConfig();
if (!config) {
console.error('No GBrain config found. Run `gbrain init` first, or set DATABASE_URL / GBRAIN_DATABASE_URL.');
process.exit(1);
}
const engineConfig = toEngineConfig(config);
const engine = await createEngine(engineConfig);
await engine.connect(engineConfig);
async function run(): Promise<number> {
let usage: ClientOpUsage[];
try {
const read = await readClientOpUsageWithCoverage(engine, { days });
// Partial data must never derive the starter surface: refuse a window that reaches past pruned history.
if (read.coverage.truncated) {
console.error(truncatedWindowNote(read.coverage));
return 1;
}
usage = read.clients;
} catch (e) {
// A brain that never served remote MCP may lack the table entirely.
console.error('Could not read mcp_request_log — has this brain ever served remote MCP?');
console.error(` ${e instanceof Error ? e.message : String(e)}`);
return 1;
}
const automation = usage.filter((u) => u.likely_automation);
const real = usage.filter((u) => !u.likely_automation);
const knownOps = new Map(operations.map((o) => [o.name, o]));
// Client-count ranking over per-client DISTINCT-op sets (D12).
const clientCount = new Map<string, number>();
const callCount = new Map<string, number>();
const skippedUnknown = new Set<string>();
for (const u of real) {
for (const op of u.distinct_ops) {
const known = knownOps.get(op);
if (!known) {
skippedUnknown.add(op); // attempted-but-nonexistent names from error rows
continue;
}
if (known.localOnly) continue; // never proposable for a network surface
clientCount.set(op, (clientCount.get(op) ?? 0) + 1);
callCount.set(op, (callCount.get(op) ?? 0) + (u.ops[op] ?? 0));
}
}
const ranked = [...clientCount.entries()]
.sort((a, b) => b[1] - a[1] || (callCount.get(b[0]) ?? 0) - (callCount.get(a[0]) ?? 0) || (a[0] < b[0] ? -1 : 1))
.map(([op]) => op);
const derivedSlots = Math.max(0, target - ALWAYS_INCLUDED.size);
const proposal = ranked.filter((op) => !ALWAYS_INCLUDED.has(op)).slice(0, derivedSlots);
const today = new Date().toISOString().slice(0, 10);
const lines: string[] = [];
lines.push('/**');
lines.push(` * STARTER_OPS daily-driver slice — derived from production mcp_request_log.`);
lines.push(` * Provenance: window=${days}d, generated=${today}, script=scripts/derive-starter-ops.ts,`);
lines.push(` * clients=${real.length} (excluded ${automation.length} automation-shaped: >90% context_pack/delta).`);
lines.push(` * HTTP clients only — stdio does not write mcp_request_log.`);
lines.push(` * NOTE: VERB_NAMES + whoami + request_tools + the agent lane (submit_agent,`);
lines.push(` * get_agent_job) are ALWAYS included by surface.ts and are not listed here.`);
lines.push(' */');
lines.push('const DERIVED_DAILY_OPS: readonly string[] = [');
for (const op of proposal) {
lines.push(` '${op}', // ${clientCount.get(op)} client${clientCount.get(op) === 1 ? '' : 's'}, ${callCount.get(op)} calls/${days}d`);
}
lines.push('];');
console.log(`# derive-starter-ops — ${days}d window, ${usage.length} clients seen (${automation.length} automation-shaped excluded)\n`);
if (real.length === 0) {
console.log('No non-automation HTTP client usage in the window. The FOV-6b fallback');
console.log('(BRAIN_TOOL_ALLOWLIST ∪ agent lane) in src/mcp/surface.ts remains the right set.');
return 0;
}
console.log('Ranked ops (client count desc, then call count):');
for (const op of ranked) {
const marks: string[] = [];
if (ALWAYS_INCLUDED.has(op)) marks.push('always-included');
if (proposal.includes(op)) marks.push('PROPOSED');
console.log(` ${op.padEnd(28)} clients=${clientCount.get(op)} calls=${callCount.get(op)}${marks.length ? ' [' + marks.join(', ') + ']' : ''}`);
}
if (skippedUnknown.size > 0) {
console.log(`\nSkipped ${skippedUnknown.size} logged name(s) not in the operations catalog (failed-call attempts).`);
}
const allowlistMissing = [...BRAIN_TOOL_ALLOWLIST].filter(
(op: string) => !proposal.includes(op) && !ALWAYS_INCLUDED.has(op),
);
if (allowlistMissing.length > 0) {
console.log(`\nWARNING (D12 cross-check): BRAIN_TOOL_ALLOWLIST members absent from the proposal:`);
console.log(` ${allowlistMissing.join(', ')}`);
console.log(' Dropping these breaks subagent/starter parity — include them unless deliberate.');
}
console.log('\nProposed block — paste into src/mcp/surface.ts (replacing FALLBACK_DAILY_OPS),');
console.log('then run: bun test --timeout=60000 test/mcp-surface.test.ts && bun run scripts/generate-tool-catalog.ts\n');
console.log(lines.join('\n'));
return 0;
}
let exitCode = 1;
try {
exitCode = await run();
} finally {
await engine.disconnect();
}
process.exit(exitCode);