Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The one finalize step every operation gets before it runs (central area
* taxonomy + output redaction wrapper), and the CLI's per-op loader.
*
* src/core/operations.ts finalizes the whole registry as it loads. The CLI
* runs exactly one op per process, so loadOperation() imports only the module
* that defines it (src/core/operation-loaders.generated.ts) and finalizes that
* one op the same way, keeping the rest of the handler graph off the
* cold-start path. Finalizing is idempotent per op object, so a process
* that later loads operations.ts sees the same objects in the same state.
*/
import type { Operation } from './ops/contract.ts';
import { withOutputRedaction } from './search/output-redaction.ts';
import { withEngineScope } from './engine-scope.ts';
import { withGuestMarks } from './guests/marker.ts';
import { OPERATION_LOADERS } from './operation-loaders.generated.ts';
// ---------------------------------------------------------------------------
// WP4 (amendment 22) — area taxonomy.
//
// One central map (single reviewable block) rather than 100+ scattered inline
// fields. Area NAMES ARE NON-CONTRACTUAL: they group the request_tools
// catalog and the generated tool-catalog doc; renaming or regrouping is never
// a breaking change. Every non-localOnly op MUST have an area — enforced by
// the CI walker in test/mcp-tool-defs.test.ts, so a future op missing from
// this map fails at PR time. localOnly ops are covered too (harmless; the
// walker only requires non-localOnly). Ops that declare `area` inline
// (request_tools) win over this map.
// ---------------------------------------------------------------------------
const OP_AREAS: Record<string, string> = {
// memory verbs (the frozen protocol facade)
recall: 'memory-verbs', remember: 'memory-verbs', entity: 'memory-verbs',
synthesize: 'memory-verbs', forget: 'memory-verbs',
context_pack: 'memory-verbs', delta: 'memory-verbs',
// pages (CRUD, versions, raw payloads, resolution)
get_page: 'pages', put_page: 'pages', delete_page: 'pages', list_pages: 'pages', find_pages: 'pages',
restore_page: 'pages', purge_deleted_pages: 'pages', promote_guest_note: 'pages',
get_versions: 'pages', revert_version: 'pages',
resolve_slugs: 'pages', whois: 'pages', get_chunks: 'pages',
put_raw_data: 'pages', get_raw_data: 'pages',
fetch: 'pages', // #4039 deep-research read adapter (search/fetch pair)
// search
search: 'search', search_exact: 'search', query: 'search', search_by_image: 'search', assemble_evidence: 'search',
// tags
add_tag: 'tags', remove_tag: 'tags', get_tags: 'tags',
// links + graph
add_link: 'links', remove_link: 'links', get_links: 'links',
get_backlinks: 'links', list_link_sources: 'links', traverse_graph: 'links',
find_orphans: 'links', rank_entities: 'links',
wanted_pages: 'links',
// timeline
add_timeline_entry: 'timeline', get_timeline: 'timeline',
// life chronicle
chronicle_day: 'chronicle', chronicle_on_this_day: 'chronicle',
chronicle_since: 'chronicle', chronicle_last_seen: 'chronicle',
volunteer_chronicle: 'chronicle', chronicle_backfill: 'chronicle',
// ontology
ontology_get: 'ontology', ontology_propose: 'ontology',
ontology_dimensions: 'ontology', ontology_conflicts: 'ontology',
// admin + operations
get_stats: 'admin', get_health: 'admin', run_doctor: 'admin', get_brain_health: 'admin', mute_notice: 'admin',
get_status_snapshot: 'admin', run_onboard: 'admin', run_skillopt: 'admin',
migrate_embeddings: 'admin', code_traversal_cache_clear: 'admin', get_write_attribution: 'admin',
// identity
whoami: 'identity', get_brain_identity: 'identity',
// skills
list_skills: 'skills', get_skill: 'skills', list_brain_skillpack: 'skills',
get_skill_asset: 'skills', put_skill: 'skills', delete_skill: 'skills',
get_skill_policy: 'skills', set_skill_policy: 'skills', import_skill_proposal: 'skills',
get_skill_retention: 'skills', prune_skill_revisions: 'skills', retain_skill_revision: 'skills',
join_brain: 'skills', sync_brain_skills: 'skills', leave_brain: 'skills',
// advisor
advisor: 'advisor',
// sources
sources_add: 'sources', sources_list: 'sources', sources_remove: 'sources',
sources_status: 'sources', sources_resolve_path: 'sources',
// sync (localOnly)
sync_brain: 'sync',
// ingest log
log_ingest: 'ingest', get_ingest_log: 'ingest',
get_usage: 'admin',
// files (localOnly)
storage_find: 'storage', storage_get: 'storage', storage_list: 'storage',
file_list: 'files', file_upload: 'files', file_url: 'files', file_register: 'files', file_verify: 'files',
// jobs (Minions + agent lane)
submit_job: 'jobs', get_job: 'jobs', wait_job: 'jobs', list_jobs: 'jobs', cancel_job: 'jobs',
retry_job: 'jobs', get_job_progress: 'jobs', pause_job: 'jobs', watch_job: 'jobs', list_watches: 'jobs', unwatch: 'jobs',
watch_write_request: 'jobs', watch_cron: 'jobs', accept_wakeshift_terms: 'jobs',
resume_job: 'jobs', replay_job: 'jobs', send_job_message: 'jobs',
submit_agent: 'jobs', get_agent_job: 'jobs',
// takes + think
takes_list: 'takes', takes_search: 'takes', think: 'takes',
takes_scorecard: 'takes', takes_calibration: 'takes',
// hot memory (facts)
extract_facts: 'memory', forget_fact: 'memory', confirm_memory: 'memory',
memory_recall: 'memory', memory_write: 'memory', memory_propose: 'memory', // GST-359: QM's memory provider pair
// entity extraction lane
extract_entities: 'entities', extraction_pending: 'entities',
extraction_review: 'entities',
// #4224 cross-source entity identity (v1 manual-only)
entity_identity_link: 'entities', entity_identity_unlink: 'entities',
entity_identity_list: 'entities',
// v0.47 open-loop engine (google source kind)
open_loops: 'loops', loops_close: 'loops', loops_mute: 'loops', loops_unmute: 'loops',
questions_pin: 'questions', questions_list: 'questions', questions_status: 'questions', questions_refresh: 'questions', questions_unpin: 'questions', // C4
// insight / signal reads
get_recent_salience: 'insights', find_anomalies: 'insights',
find_contradictions: 'insights', find_experts: 'insights',
find_trajectory: 'insights', get_calibration_profile: 'insights',
volunteer_context: 'insights', get_recent_transcripts: 'insights',
// code intelligence
code_callers: 'code', code_callees: 'code', code_def: 'code',
code_refs: 'code', code_blast: 'code', code_flow: 'code',
// schema packs
get_active_schema_pack: 'schema', list_schema_packs: 'schema',
schema_stats: 'schema', schema_lint: 'schema', schema_graph: 'schema',
schema_explain_type: 'schema', schema_review_orphans: 'schema',
schema_apply_mutations: 'schema', reload_schema_pack: 'schema',
// discovery
request_tools: 'discovery',
};
const finalized = new WeakSet<Operation>();
/** The ops that return a write's reply or receipt: every write, and the receipt reads. */
const RECEIPT_READS = new Set(['get_write_request', 'list_write_requests', 'watch_write_request']);
/** GST-2900: a held write's reply reads as a plain save to a caller who cannot read the private copy (trust/privacy-hold-reply.ts). */
function withPrivacyHoldReplies(op: Operation, handler: Operation['handler']): Operation['handler'] {
if (op.mutating !== true && !RECEIPT_READS.has(op.name)) return handler;
return async (ctx, params) => {
const result = await handler(ctx, params);
if (ctx.remote === false || typeof ctx.engine?.executeRaw !== 'function') return result;
const grant = op.mutating === true ? ctx.auth?.privateFacts?.sources : undefined;
return (await import('./trust/privacy-hold-reply.ts')).hidePrivacyHoldRefs(ctx.engine, ctx.remote, result, grant);
};
}
export function finalizeOperation(op: Operation): void {
if (finalized.has(op)) return;
finalized.add(op);
if (op.area === undefined && OP_AREAS[op.name] !== undefined) {
op.area = OP_AREAS[op.name];
}
// The handler runs in its engine's scope, so an embedded engine's AI calls use that engine's gateway (engine-scope.ts).
// Redaction runs after the guest stamp, so a key-like sender label in a guest mark is redacted like stored text.
const handler = withOutputRedaction({ handler: withPrivacyHoldReplies(op, withGuestMarks(op, op.handler)), outputRedaction: op.outputRedaction });
op.handler = (ctx, params) => withEngineScope(ctx.engine, () => handler(ctx, params));
}
/** The finalized operation named `name`, loading only the module that defines it. */
export async function loadOperation(name: string): Promise<Operation | undefined> {
const entry = OPERATION_LOADERS[name];
if (!entry) return undefined;
const [load, exportName] = entry;
const exported = (await load())[exportName] as Operation | Operation[];
const op = Array.isArray(exported) ? exported.find(o => o.name === name) : exported;
if (op) finalizeOperation(op);
return op;
}