Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Insight-read operation cluster — pure move from operations.ts (v0.46.x
* tranche 3): the v0.43 push-based-context op (volunteer_context) plus the
* find_* insight reads (find_experts, find_contradictions, find_trajectory).
* Unlike the other tranche-3 clusters these four occupy NON-adjacent slots of
* the canonical `operations` array in ../operations.ts, so the ops are
* exported individually and spliced as bare entries at their original
* positions (order is contractual — docs/TOOL_CATALOG.md is generated from
* it). Never import from '../operations.ts' here (cycle).
*/
import { MIN_TRUST_PARAM, resolveReadEligibility } from '../eligibility/policy.ts';
import { resolveScopedFindings } from '../eval-contradictions/scoped-read.ts';
import type { ProbeReport } from '../eval-contradictions/types.ts';
import { proactiveEligibility } from '../eligibility/registry.ts';
import { activationSuppressionNotice, suppressionSummary } from '../eligibility/activation.ts';
import type { Operation } from './contract.ts';
import { opError } from './contract.ts';
import { invalidParam, paramUse } from './op-fix.ts';
import { federatedSearchScope, sourceScopeOpts, readPolicyOpts } from './context.ts';
import { parseSourceIdsParam, requestSourceScope, SOURCE_IDS_PARAM } from './search-source-scope.ts';
import { currentReadMode } from '../access/scope-read.ts';
import {
FIND_EXPERTS_DESCRIPTION,
FIND_CONTRADICTIONS_DESCRIPTION,
FIND_TRAJECTORY_DESCRIPTION,
} from '../operations-descriptions.ts';
// --- v0.43 (#2095): push-based context — the brain volunteers pages ---
const volunteer_context: Operation = {
name: 'volunteer_context',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description:
'Push-based context: volunteer brain pages relevant to a rolling conversation window ' +
'WITHOUT being asked. Zero-LLM, confidence-gated (alias 0.9 / exact-title 0.8 / ' +
'slug-suffix 0.6, +0.05 for multi-turn or newest-turn mentions; default gate 0.7), ' +
'capped at 3 pages (max 5). Returns pointers with one-line rationales + synopses — ' +
'open the page (get_page) before relying on details. Pass stats: true for the ' +
'approximate volunteered-vs-used precision summary (the feedback loop).',
scope: 'read',
params: {
window: {
type: 'string',
description:
"Recent conversation turns, oldest → newest, as 'user:' / 'assistant:' prefixed " +
'lines (unprefixed text = one user turn). Required unless stats: true. ' +
'CLI: piped stdin fills this.',
},
prior_context: {
type: 'string',
description:
'Already-surfaced context (pointer blocks / opened page bodies). Pages whose slug ' +
'appears here are not re-volunteered.',
},
max_pages: { type: 'number', description: 'Max pages to volunteer (default 3, hard cap 5).' },
min_trust: MIN_TRUST_PARAM,
min_confidence: {
type: 'number',
description:
'Confidence gate 0..1 (default 0.7 — slug-suffix matches need an explicit lower gate).',
},
session_id: { type: 'string', description: 'Optional caller session id, logged for attribution.' },
turn: { type: 'number', description: 'Optional caller turn number, logged for attribution.' },
stats: {
type: 'boolean',
description:
'Return the volunteered-vs-used precision summary instead of volunteering. ' +
'APPROXIMATE: "used" = pages.last_retrieved_at > volunteered_at.',
},
days: { type: 'number', description: 'Stats window in days (default 30; stats mode only).' },
source_ids: SOURCE_IDS_PARAM,
},
handler: async (ctx, p) => {
const { parseWindow, volunteerContext, volunteerUsageStats } = await import('../context/volunteer.ts');
// GST-1158 E1: under the scope record the stats summary (volunteering across whole sources) is refused.
const asScope = currentReadMode() === 'scope';
if (p.stats === true && asScope) {
throw invalidParam(ctx, 'volunteer_context', 'stats', '`stats` summarizes volunteering across whole sources, so a call that names sources as their audience cannot ask for it.', { example: false });
}
const named = parseSourceIdsParam(ctx, 'volunteer_context', p.source_ids);
const scope = named === undefined ? sourceScopeOpts(ctx) : await requestSourceScope(ctx, undefined, named);
const sourceIds = scope.sourceIds ?? (scope.sourceId ? [scope.sourceId] : ['default']);
if (p.stats === true) {
return volunteerUsageStats(ctx.engine, sourceIds, typeof p.days === 'number' ? p.days : undefined);
}
if (typeof p.window !== 'string' || !p.window.trim()) {
throw opError(
'invalid_params',
`window is required unless ${paramUse(ctx, 'stats')}`,
`${ctx.remote === false ? 'Pipe the recent turns on stdin' : 'Pass `window` with the recent turns as a string'}, or pass ${paramUse(ctx, 'stats')} for the volunteered-vs-used summary.`,
);
}
const turns = parseWindow(p.window);
const { loadConfig: loadCfgForArms } = await import('../config.ts');
const { lexicalArmsEnabled } = await import('../context/reflex.ts');
const { resolveExcludePrivatePages } = await import('../search/private-visibility.ts');
const withheldKeys = new Set<string>();
const pages = await volunteerContext(ctx.engine, turns, {
sourceIds,
priorContext: typeof p.prior_context === 'string' ? p.prior_context : undefined,
maxPages: typeof p.max_pages === 'number' ? p.max_pages : undefined,
minConfidence: typeof p.min_confidence === 'number' ? p.min_confidence : undefined,
// v0.46.15+ kill switch for the lexical recall arms (weak-alias +
// surname) — file-plane gate, threaded per ResolvePointersOpts.
lexicalArms: lexicalArmsEnabled(loadCfgForArms()),
// N8-1: the same private-page gate remote search applies.
excludePrivate: asScope || await resolveExcludePrivatePages(ctx.engine, ctx.remote),
// #5575: token floor + min_trust + activation control (CEO-20, DX-10).
eligibility: await proactiveEligibility(ctx, 'volunteer', { minTrust: p.min_trust }),
onWithheld: keys => { for (const k of keys) withheldKeys.add(k); },
});
const withheld = withheldKeys.size;
const notice = activationSuppressionNotice(withheld, 'volunteered context');
if (notice) ctx.emitNotice?.(notice);
// Feedback-loop logging: fire-and-forget batched INSERT through the
// volunteer-events sink (drained at exit). Never fails the op.
if (pages.length) {
try {
const { logVolunteerEventsFireAndForget, volunteerEventRowsFrom, SESSION_ID_MAX_LEN } = await import('../context/volunteer-events.ts');
// Trust-boundary clamps (remote MCP callers): cap session_id length so
// a read-scoped token can't bank unbounded TEXT per request, and only
// log integer turns — a non-integer would throw inside the single
// multi-row INSERT and silently drop the whole batch.
const sessionId = typeof p.session_id === 'string' ? p.session_id.slice(0, SESSION_ID_MAX_LEN) : null;
const turn =
typeof p.turn === 'number' && Number.isInteger(p.turn) && Math.abs(p.turn) <= 2_147_483_647
? p.turn
: null;
logVolunteerEventsFireAndForget(
ctx.engine,
volunteerEventRowsFrom(pages, { channel: 'op', session_id: sessionId, turn }),
);
} catch {
/* telemetry only */
}
}
const suppressed = suppressionSummary(withheld);
return { pages, count: pages.length, window_turns: turns.length, ...(suppressed ? { suppressed } : {}) };
},
cliHints: { name: 'volunteer-context', stdin: 'window' },
};
// v0.33: expertise + relationship-proximity routing. CLI: gbrain whoknows.
const find_experts: Operation = {
name: 'find_experts',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description: FIND_EXPERTS_DESCRIPTION,
scope: 'read',
params: {
topic: {
type: 'string',
description: 'The topic to route. Free-form natural language.',
},
limit: {
type: 'number',
description: 'Max results (default 5).',
},
explain: {
type: 'boolean',
description: 'Include factor breakdown per result (expertise, recency, salience).',
},
source_ids: SOURCE_IDS_PARAM,
},
handler: async (ctx, p) => {
const { findExperts } = await import('../../commands/whoknows.ts');
const topic = typeof p.topic === 'string' ? p.topic : '';
if (!topic.trim()) {
throw invalidParam(ctx, 'find_experts', 'topic', '`topic` is required and must be a non-empty string.',
{ def: find_experts.params.topic, example: 'vector search' });
}
// v0.34.1 (#861, D3 — 5th leak surface): find_experts (whoknows) was
// authored against v0.33 after PR #861 was drafted, so the source-scope
// thread was missing entirely. The op calls findExperts → hybridSearch
// internally; without the thread an auth'd src-A whoknows query would
// surface src-B people in the rankings.
// v0.40.6.0 T1.5 wiring (D4): consult the active pack for expert
// types; pack-load failure → empty filter (NOT hardcoded defaults
// per the silent-violation bug class Finding 1.3 closed).
const { loadActivePackBestEffort, expertTypesFromPack } = await import('../schema-pack/index.ts');
const pack = await loadActivePackBestEffort(ctx);
const types = pack ? expertTypesFromPack(pack.manifest) : [];
const sourceIds = parseSourceIdsParam(ctx, 'find_experts', p.source_ids);
const scope = await readPolicyOpts(ctx, sourceIds === undefined ? undefined : await requestSourceScope(ctx, undefined, sourceIds));
let degraded: unknown[] = [];
const experts = await findExperts(ctx.engine, {
topic,
limit: typeof p.limit === 'number' ? p.limit : undefined,
explain: p.explain === true,
types: types as never,
...scope,
onMeta: m => { degraded = m.degraded ?? []; },
});
// GBRA-200: a keyword-only or cut ranking is stamped like search, never read as "nobody knows".
if (degraded.length) ctx.emitResponseMeta?.('retrieval', { degraded });
return experts;
},
// hidden: 'whoknows' is in CLI_ONLY (src/cli.ts) — runWhoknows owns the CLI
// surface (ranked table + per-factor explain + thin-client routing) and was
// unreachable while this non-hidden hint dispatched the generic op formatter
// (the #2035 calibration bug class, resolved the #3502 way: wire the richer
// handler, hide the hint).
cliHints: { name: 'whoknows', positional: ['topic'], hidden: true },
};
// v0.32.6: contradiction probe MCP surface (M3)
const find_contradictions: Operation = {
name: 'find_contradictions',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description: FIND_CONTRADICTIONS_DESCRIPTION,
scope: 'read',
// Reads eval_contradictions_runs.report_json for the latest run, then
// filters in-memory by slug and severity. No new probe is triggered;
// the agent surfaces what's already on disk. Scoped readers (remote,
// source-scoped or floored) get each side re-read live (D9, scoped-read.ts).
params: {
slug: {
type: 'string',
description: 'Optional slug filter; matches either side of a pair (substring match on slug).',
},
severity: {
type: 'string',
enum: ['low', 'medium', 'high'],
description: 'Optional severity filter.',
},
limit: {
type: 'number',
description: 'Max findings to return. Default 20.',
},
min_trust: MIN_TRUST_PARAM,
},
handler: async (ctx, p) => {
const scope = sourceScopeOpts(ctx);
// N2-2: the local CLI always carries a sourceId; one the operator did not
// select is not a filter, so the bare command reads the latest run.
const sourceFiltered = scope.sourceIds !== undefined
|| (scope.sourceId !== undefined && ctx.localSourceImplicit !== true);
const { floor } = await resolveReadEligibility(ctx, { minTrust: p.min_trust });
const scoped = ctx.remote !== false || sourceFiltered || floor !== undefined;
const readScope = ctx.remote === false && !sourceFiltered ? {} : federatedSearchScope(ctx);
if (scoped && ctx.remote !== false && readScope.sourceId === undefined && readScope.sourceIds === undefined) {
return { contradictions: [], note: 'This connection names no readable source, so no stored contradiction findings are returned.' };
}
const limit = typeof p.limit === 'number' && p.limit > 0 ? Math.min(p.limit, 100) : 20;
const slugFilter = typeof p.slug === 'string' ? p.slug.toLowerCase() : null;
const sevFilter = (p.severity === 'low' || p.severity === 'medium' || p.severity === 'high')
? p.severity
: null;
const rows = await ctx.engine.loadContradictionsTrend(30);
if (rows.length === 0) {
return { contradictions: [], note: 'No probe runs in the last 30 days; run `gbrain eval suspected-contradictions` first.' };
}
const latest = rows[0];
const report = latest.report_json as Partial<ProbeReport> | null;
const allFindings = (report?.per_query ?? []).flatMap((q) => q.contradictions ?? []);
const matches = (f: { severity: string; a: { slug: string }; b: { slug: string } }) => {
if (sevFilter && f.severity !== sevFilter) return false;
if (slugFilter) {
const sA = f.a.slug.toLowerCase();
const sB = f.b.slug.toLowerCase();
if (!sA.includes(slugFilter) && !sB.includes(slugFilter)) return false;
}
return true;
};
if (scoped) {
// D9: every side is re-read live under the caller's policy; stored text,
// totals and commands never leave for a scoped reader.
const visible = (await resolveScopedFindings(ctx.engine, allFindings, await readPolicyOpts(ctx, readScope), floor)).filter(matches);
return {
run_id: latest.run_id,
ran_at: latest.ran_at,
contradictions: visible.slice(0, limit),
total_visible: visible.length,
};
}
// This branch is trusted, unscoped and unfloored. Apply the requested
// display filters before the limit.
const kept = allFindings.filter(matches).slice(0, limit);
return {
run_id: latest.run_id,
ran_at: latest.ran_at,
contradictions: kept,
// Trusted unscoped callers retain the complete local run count.
total_in_run: allFindings.length,
};
},
cliHints: { name: 'find-contradictions' },
};
const find_trajectory: Operation = {
name: 'find_trajectory',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
description: FIND_TRAJECTORY_DESCRIPTION,
scope: 'read',
// localOnly intentionally NOT set — federated OAuth clients should be
// able to query trajectories for entities in their scope. Visibility
// filtering (D-CDX-1) inside the engine restricts remote callers to
// visibility='world' facts.
params: {
entity_slug: {
type: 'string',
description: 'Required. Entity slug to chart (e.g. "companies/acme-example", "people/alice-example").',
},
metric: {
type: 'string',
description: 'Optional. Filter to a single canonical metric (e.g. "mrr", "arr", "team_size"). When omitted, all metrics return.',
},
kind: {
type: 'string',
enum: ['metric', 'event', 'all'],
description: 'Optional. Filter by row shape: "metric" (typed-claim rows only), "event" (event_type rows only), or "all" (default). v0.40.2.0+.',
},
since: {
type: 'string',
description: 'Optional lower bound on valid_from (YYYY-MM-DD or ISO).',
},
until: {
type: 'string',
description: 'Optional upper bound on valid_from (YYYY-MM-DD or ISO).',
},
limit: {
type: 'number',
description: 'Max points returned. Default 100, max 500.',
},
},
handler: async (ctx, p) => {
if (typeof p.entity_slug !== 'string' || !p.entity_slug.trim()) {
throw invalidParam(ctx, 'find_trajectory', 'entity_slug', 'find_trajectory requires entity_slug (string)', { example: 'people/alice-example' });
}
const metric = typeof p.metric === 'string' ? p.metric : undefined;
const kind = (p.kind === 'metric' || p.kind === 'event' || p.kind === 'all')
? (p.kind as 'metric' | 'event' | 'all')
: undefined;
const since = typeof p.since === 'string' ? p.since : undefined;
const until = typeof p.until === 'string' ? p.until : undefined;
const limit = typeof p.limit === 'number' ? p.limit : undefined;
const scope = sourceScopeOpts(ctx);
const { resolveExcludePrivatePages, worldOnlyFacts } = await import('../search/private-visibility.ts');
// D-CDX-1: the engine filters visibility in SQL. GST-2951: world-only for every remote caller but the brain owner,
// as recall and think's trajectory (worldOnlyFacts); page rules still apply through excludePrivate.
const points = await ctx.engine.findTrajectory({
entitySlug: p.entity_slug,
...scope,
remote: worldOnlyFacts(ctx.remote),
excludePrivate: await resolveExcludePrivatePages(ctx.engine, ctx.remote),
metric,
kind,
since,
until,
limit,
});
const { computeTrajectoryStats, TRAJECTORY_SCHEMA_VERSION } = await import('../trajectory.ts');
const { regressions, drift_score } = computeTrajectoryStats(points);
// Engine result includes raw embeddings (Float32Array); strip those
// before sending over MCP — they're bulky binary noise that consumers
// never need at this layer.
// v0.40.2.0: event_type surfaces on the wire so remote callers (thin-
// client think, founder-scorecard) see the event-shaped rows.
const wirePoints = points.map(pt => ({
fact_id: pt.fact_id,
valid_from: pt.valid_from.toISOString().slice(0, 10),
metric: pt.metric,
value: pt.value,
unit: pt.unit,
period: pt.period,
event_type: pt.event_type,
text: pt.text,
source_session: pt.source_session,
source_markdown_slug: pt.source_markdown_slug,
}));
return {
points: wirePoints,
regressions,
drift_score,
schema_version: TRAJECTORY_SCHEMA_VERSION,
};
},
cliHints: { name: 'find-trajectory' },
};
export { volunteer_context, find_experts, find_contradictions, find_trajectory };