Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Derive the subagent brain-tool registry from src/core/operations.ts.
*
* Single source of truth: the MCP server already maps OPERATIONS → tool defs.
* We reuse the same ParamDef-shape → JSONSchema conversion (lives in
* buildToolDefs for MCP) and wrap each allowed op with an execute() that
* invokes its handler under a subagent-tagged OperationContext.
*
* Filtering is NAME-based (not by OperationContext.remote, which is a
* call-time flag, not operation metadata — codex catch). The allow-list
* below is reviewed manually; adding a new op here is an explicit security
* decision.
*
* put_page: allowed, but the subagent tool-schema wraps its `slug` with a
* per-subagent namespace regex so the model can only write under
* `wiki/agents/<subagentId>/...`. The put_page operation also has a server-
* side fail-closed check (see src/core/operations.ts) that catches any
* dispatcher bug where viaSubagent=true but subagentId is missing.
*
* In v0.15 every allow-list op is treated as idempotent for the two-phase
* replay path. put_page with its persisted request UUID is idempotent at the journal
* level; repeats re-derive the same embedding over identical content.
*/
import { budgetedPageRead } from './read-budget.ts';
import type { BrainEngine } from '../../engine.ts';
import type { GBrainConfig } from '../../config.ts';
import { operations } from '../../operations.ts';
import type { AuthInfo, Operation, OperationContext } from '../../operations.ts';
import { paramDefToSchema } from '../../../mcp/tool-defs.ts';
import { normalizeOptionalParams, validateParams } from '../../../mcp/validate-params.ts';
import { validateSourceId } from '../../utils.ts';
import type { ToolCtx, ToolDef } from '../types.ts';
import { putPageRejection, rethrowWithCurrentRevision } from './put-page-result.ts';
import { BRAIN_TOOL_ALLOWLIST } from './brain-tool-allowlist.ts';
import { stagePutPage } from './staged-put-page.ts';
import { withCallerAccess } from '../../search/private-visibility.ts';
import { remoteCallerAccess } from '../../access/caller.ts';
import { credentialScopeFor, requesterScopeGate, requiresRequesterScope, withServesReread } from '../../access/requester-scope.ts';
import { attestedCallerAccess, attestRightOf, storedActorIdentity } from '../../access/actor.ts';
import { attestedReadMode, scopeReadAccess, withReadMode } from '../../access/scope-read.ts';
import { attestedReadScope } from '../../access/member-sources.ts';
import type { AudiencePrincipal } from '../../access/audience.ts';
import { currentSubmissionAuthority } from '../submission-authority.ts';
// The allow-list itself lives in a handler-free module so the MCP surface
// tiers (src/mcp/surface.ts) can read it without this module's operations import.
export { BRAIN_TOOL_ALLOWLIST };
/**
* v0.41 Approach C: per-tool usage_hint surfaced verbatim in the subagent
* system prompt's tool preamble. Each entry tells the model WHEN to reach
* for the tool (the description tells the model HOW). One line per tool;
* no embedded newlines.
*
* Field-report driver: the renderer in `src/core/minions/system-prompt.ts`
* surfaces these so a model with `shell` + brain tools in its registry
* knows brain tools write to the gbrain DB (NOT local files) and to reach
* for shell when the task asks for filesystem work.
*
* Keyed by OP name (pre-`brain_` prefix). Optional — tools without an entry
* just render as `- \`name\`` with no hint suffix.
*/
export const BRAIN_TOOL_USAGE_HINTS: Readonly<Record<string, string>> = {
query: 'Use for natural-language semantic search across the brain (vector + keyword hybrid). Returns ranked passages with citations. First choice when the user asks a question of the brain.',
search: 'Use for hybrid keyword + vector search returning ranked page hits. Use over `query` when you want page-level not chunk-level results (e.g. "find pages about X").',
get_page: 'Read a brain page by its slug. Returns the full markdown body + frontmatter + linked pages.',
list_pages: 'List pages by type or slug-prefix filter. Use when you need to enumerate (e.g. "list all `people/` pages") instead of search.',
get_backlinks: 'List every page that links TO the given slug. Use for "what references this".',
traverse_graph: 'Walk the typed-edge graph starting from a slug (e.g. `works_at`, `founded`, `invested_in`). Use for relationship queries.',
list_link_sources: 'List the distinct link provenances in the brain with edge counts (e.g. `citation-graph`, `manual`). Use to discover which edge-writers have populated the graph.',
resolve_slugs: 'Resolve free-form entity names to canonical slugs (e.g. "Alice" → `people/alice-example`). Use before any tool that takes a slug if the user gave a name not a slug.',
get_ingest_log: 'Read the brain ingestion log for diagnostic / verification queries.',
put_page: 'Write a markdown page to the gbrain DATABASE (NOT the local filesystem). Page becomes searchable + linkable. Slug must match the agent\'s allowed namespace.',
add_timeline_entry: 'Append a dated timeline entry to an existing page (the canonical timeline write). Use over rewriting the page body when recording a dated event. Slug must match the agent\'s allowed namespace.',
get_recent_salience: 'Read pages ranked by emotional + activity salience over a recency window. Use for "what\'s been on my mind lately".',
find_anomalies: 'Read cohort-level activity outliers (e.g. tag-cohort or type-cohort with unusual recent volume). Use for "what\'s unusual lately".',
};
/** Matches Anthropic's tool-name constraint. No dots. */
const ANTHROPIC_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
function sanitizeToolName(opName: string): string {
// Prefix with brain_ and replace any non-conforming char. For the v0.15
// allow-list, every op name is already a valid simple identifier, so this
// is defense-in-depth.
const prefixed = `brain_${opName}`.replace(/[^a-zA-Z0-9_-]/g, '_');
return prefixed.slice(0, 64);
}
/**
* Convert an Operation.params (ParamDef) map to an Anthropic-compatible
* JSONSchema.input_schema. Same shape MCP uses inline — ParamDef.type
* narrows to a subset of JSONSchema types.
*/
function paramsToInputSchema(op: Operation): Record<string, unknown> {
return {
type: 'object' as const,
properties: Object.fromEntries(
Object.entries(op.params).map(([k, v]) => [k, paramDefToSchema(v)]),
),
required: Object.entries(op.params).filter(([, v]) => v.required).map(([k]) => k),
};
}
/**
* For put_page specifically, the tool schema shown to the model constrains
* `slug`. Two modes:
*
* - Default (legacy): slug MUST start with `wiki/agents/<subagentId>/`,
* enforced by both the JSONSchema `pattern` and the server-side check.
* - Trusted-workspace (v0.23 dream cycle): when `allowedSlugPrefixes` is
* set, the model is told the allowed prefixes in plain English (no
* regex pattern — the prefix list is authoritative server-side, and
* JSONSchema can't express "matches any of these globs" cleanly).
*/
function namespacedPutPageSchema(
op: Operation,
subagentId: number,
allowedSlugPrefixes?: readonly string[],
): Record<string, unknown> {
const base = paramsToInputSchema(op);
const props = (base.properties as Record<string, Record<string, unknown>>) ?? {};
if (props.slug) {
if (allowedSlugPrefixes && allowedSlugPrefixes.length > 0) {
props.slug = {
...props.slug,
description:
`Page slug. MUST match one of these prefix globs: ${allowedSlugPrefixes.join(', ')}. ` +
`Slugs use lowercase alphanumeric segments separated by '/'. No leading slash, no '.md' extension, no underscores.`,
};
} else {
props.slug = {
...props.slug,
description: `Page slug. MUST start with "wiki/agents/${subagentId}/" (agents can only write under their own namespace).`,
pattern: `^wiki/agents/${subagentId}/.+`,
};
}
}
return { ...base, properties: props };
}
/** Args required to build the registry for a given subagent job. */
export interface BuildBrainToolsOpts {
subagentId: number;
engine: BrainEngine;
config: GBrainConfig;
/**
* #4216 — defer chunk embeddings on put_page writes (oneshot programmatic
* writes only; the standing embed machinery backfills). Server-side flag.
*/
deferEmbeds?: boolean;
/** Optional filter: only include names in this set. */
allowedNames?: ReadonlySet<string>;
/**
* Connected-gbrains brain id (v0.19+, PR 0 plumbing only).
*
* CURRENT BEHAVIOR: `brainId` is stamped onto each tool-call's
* `OperationContext.brainId` for audit / logging, but `ctx.engine` is
* still the engine passed in here (the parent job's engine). Ops
* targeting mounted brains via brainId WITHOUT a registry lookup will
* silently run against the parent engine.
*
* FUTURE (PR 1): `buildOpContext` will call `BrainRegistry.getBrain
* (brainId).engine` to select the right engine per dispatch. Once
* wired, `opCtx.engine` will match `opCtx.brainId`. Until then, treat
* brainId as metadata only.
*/
brainId?: string;
/**
* Trusted-workspace allow-list (v0.23). When set, put_page is bounded
* to slugs matching these prefix globs instead of the legacy
* `wiki/agents/<id>/...` namespace. Trusted local jobs get these from the
* submitter; remote-owned jobs get the validated grant intersection and
* delegatedAuth. Prefixes alone do not make a remote job trusted.
*/
allowedSlugPrefixes?: readonly string[];
/**
* Brain source every tool-call OperationContext is scoped to (#1586).
* Remote-owned jobs also carry delegatedAuth.allowedSources so a per-call
* source_id cannot override this boundary. Validated at build time.
* Unset → legacy 'default'.
*/
sourceId?: string;
/** Current remote owner grant; never populated from caller tool arguments. */
delegatedAuth?: Pick<AuthInfo, 'clientId' | 'scopes' | 'sourceId' | 'allowedSources' | 'allowedOperations'>;
/** #6297: byte budget on this job's get_page results (SubagentHandlerData.read_budget_bytes); unset = none. */
readBudgetBytes?: number;
/** GBRA-60: put_page stages its page in the tool-execution ledger instead of writing it (SubagentHandlerData.stage_writes). */
stageWrites?: boolean;
}
interface OpContextDeps {
engine: BrainEngine;
config: GBrainConfig;
subagentId: number;
jobId: number;
signal?: AbortSignal;
brainId?: string;
allowedSlugPrefixes?: readonly string[];
sourceId?: string;
deferEmbeds?: boolean;
delegatedAuth?: BuildBrainToolsOpts['delegatedAuth'];
}
function buildOpContext(deps: OpContextDeps): OperationContext {
return {
engine: deps.engine,
config: deps.config,
logger: {
info: (msg: string) => process.stderr.write(`[subagent-tool:${deps.jobId}] ${msg}\n`),
warn: (msg: string) => process.stderr.write(`[subagent-tool:${deps.jobId}] WARN: ${msg}\n`),
error: (msg: string) => process.stderr.write(`[subagent-tool:${deps.jobId}] ERROR: ${msg}\n`),
},
dryRun: false,
remote: true, // match MCP trust boundary for auto-link skip
// #1586: cycle-resolved source when provided; legacy host default else.
sourceId: deps.sourceId ?? 'default',
// Preserve explicit per-call source checks without importing direct-write
// fences or requiring direct read/write scopes for agent-only grants.
...(deps.delegatedAuth ? { auth: { token: '', ...deps.delegatedAuth,
principal: { kind: 'oauth_client' as const, id: deps.delegatedAuth.clientId } } } : {}),
jobId: deps.jobId,
subagentId: deps.subagentId,
viaSubagent: true, // FAIL-CLOSED: put_page etc. enforce namespace
brainId: deps.brainId,
allowedSlugPrefixes: deps.allowedSlugPrefixes
? [...deps.allowedSlugPrefixes]
: undefined,
// #4216: server-side-only — the oneshot runner defers chunk embeddings on
// its programmatic writes; never hydrated from any wire payload.
...(deps.deferEmbeds ? { deferEmbeds: true } : {}),
};
}
/**
* Build the subagent brain-tool registry. One ToolDef per allow-listed op,
* with a namespace-wrapped schema for put_page.
*
* Call this once per subagent-job claim; the registry is keyed to the job's
* subagentId + engine handle, so it's not shareable across jobs.
*/
export function buildBrainTools(opts: BuildBrainToolsOpts): ToolDef[] {
const filter = opts.allowedNames ?? BRAIN_TOOL_ALLOWLIST;
const picked: Operation[] = operations.filter(
op => !op.localOnly && BRAIN_TOOL_ALLOWLIST.has(op.name) && filter.has(op.name),
);
// #1586: fail fast on a malformed source id before any tool executes
// (defense-in-depth — the seam is trusted, but the value round-trips
// through the job payload).
if (opts.sourceId !== undefined) validateSourceId(opts.sourceId);
return picked.map(op => brainTool(op, opts));
}
/**
* GBRA-60: the `put_pages` tool of a trusted dream synthesis child's oneshot runner, which writes its validated pages
* as one batch so a Postgres consumer publishes them as one group (one commit on a strict source). It is never in
* the registry a model sees: BRAIN_TOOL_ALLOWLIST keeps put_pages out, and the oneshot runner is its only caller.
*/
export function buildBrainPutPagesTool(opts: BuildBrainToolsOpts): ToolDef {
if (opts.sourceId !== undefined) validateSourceId(opts.sourceId);
return brainTool(operations.find(op => op.name === 'put_pages')!, opts);
}
/** One subagent tool: `op` under a subagent-tagged OperationContext, with a namespace-wrapped schema for put_page. */
function brainTool(op: Operation, opts: BuildBrainToolsOpts): ToolDef {
const schema = op.name === 'put_page'
? namespacedPutPageSchema(op, opts.subagentId, opts.allowedSlugPrefixes)
: paramsToInputSchema(op);
const toolName = sanitizeToolName(op.name);
if (!ANTHROPIC_NAME_RE.test(toolName)) {
throw new Error(`brain tool name ${toolName} does not match Anthropic constraint`);
}
return {
name: toolName,
description: op.description,
input_schema: schema,
// The persisted tool dispatcher binds mutations to a stable request UUID;
// a replay returns the original durable receipt without another write.
idempotent: true,
// v0.41 Approach C: surface usage_hint to the system-prompt renderer.
// Keyed by the unprefixed op name. Undefined when no hint is registered.
usage_hint: BRAIN_TOOL_USAGE_HINTS[op.name],
async execute(input: unknown, ctx: ToolCtx): Promise<unknown> {
if (op.localOnly) throw new Error(`${toolName}: local-only operations cannot be delegated`);
const opCtx = buildOpContext({
engine: ctx.engine,
config: opts.config,
subagentId: opts.subagentId,
jobId: ctx.jobId,
signal: ctx.signal,
brainId: opts.brainId,
allowedSlugPrefixes: opts.allowedSlugPrefixes,
sourceId: opts.sourceId,
deferEmbeds: opts.deferEmbeds,
delegatedAuth: opts.delegatedAuth,
});
const raw = (input && typeof input === 'object') ? input as Record<string, unknown> : {};
// Same order the MCP dispatchers keep: normalize the optional-param
// absent idioms (`null`, `''` on a string) FIRST — the validator's
// header calls this load-bearing — then validate, so a missing
// required param (or wrong type / unknown enum) is named back to the
// model instead of crashing inside the handler, and `since: ""` never
// reaches a handler raw.
const params = normalizeOptionalParams(op, raw);
// #6297: a subagent's full-content read returns the round-trip fields only, not the body twice.
if (op.name === 'get_page' && params.include_content === true) params.content_only = true;
const validationError = validateParams(op, params);
if (validationError) throw new Error(`${toolName}: ${validationError}`);
const write = op.name === 'put_page' && opts.stageWrites ? stagePutPage : op.handler;
const run = (c: typeof opCtx = opCtx) => op.name === 'put_page'
? write(c, params).catch(e => rethrowWithCurrentRevision(ctx.engine, c.sourceId ?? 'default', params.slug, e))
: op.handler(c, params);
// GBRA-218: a remote-owned job reads as its client's member, looked up live on every call (a disabled member or
// removed binding takes effect at the next tool call); never a GBRA-156 private-pages grant.
// GBRA-231: a job a shared agent submitted for an audience reads as that audience, re-checked the same way.
const submitted = currentSubmissionAuthority();
const actingFor = submitted?.kind === 'remote_agent' ? submitted.grant.actingFor as AudiencePrincipal[] | undefined : undefined;
// GST-359 C1: a job submitted for an attested actor reads as that member only while actorCoverage still covers it.
const agent = submitted?.kind === 'remote_agent' ? submitted : undefined;
const actor = agent?.grant.actor;
// GST-1158 E1: and a job tool call that names sources reads them as the scope, exactly as the same call through MCP dispatch.
const output = agent && actor
? await (async () => {
const identity = await storedActorIdentity(ctx.engine, agent.principal, actor, op.name);
const readMode = attestedReadMode(op.name, params, (await attestRightOf(ctx.engine, { principal: agent.principal }))?.read);
const access = readMode === 'scope' ? await scopeReadAccess(ctx.engine) : await attestedCallerAccess(ctx.engine, actor, identity);
return withCallerAccess(access, () => withReadMode(readMode, async () => run(await attestedReadScope(ctx.engine, opCtx, actor.member, readMode === 'scope'))));
})()
: opCtx.auth
? await withCallerAccess(await scopedJobAccess(ctx.engine, op, opCtx.auth, actingFor), run)
: await run();
const rejection = op.name === 'put_page' ? putPageRejection(output) : null;
if (rejection) throw new Error(rejection);
if (op.name === 'get_page' && opts.readBudgetBytes) return budgetedPageRead(ctx.engine, ctx.jobId, opts.readBudgetBytes, params.slug, output);
return output;
},
};
}
/**
* The caller access of a remote-owned job's tool call. GST-363: the same requester-scope gate as dispatch, read live
* on every call: on a brain that serves several people, a read by a job whose credential is bound to nobody (and that
* names no audience) is refused with requester_scope_required once the grace ends; during it the call runs.
*/
async function scopedJobAccess(engine: BrainEngine, op: Operation, auth: NonNullable<OperationContext['auth']>, actingFor: AudiencePrincipal[] | undefined) {
const access = await remoteCallerAccess(engine, auth, [], undefined, actingFor, undefined, op.mutating === false);
if (!requiresRequesterScope(op, auth)) return access;
const credential = await credentialScopeFor(engine, auth);
const resolved = await withServesReread(engine, access, credential);
requesterScopeGate(op, resolved, credential, 'http');
return resolved;
}
/**
* Apply the caller's `allowed_tools` subset to a registry. Unknown tool
* names throw a clear error at load time (NOT silently ignored) so
* subagent defs with a typo don't ship to prod wondering why a tool
* never fires.
*/
export function filterAllowedTools(registry: ToolDef[], allowedToolNames: string[]): ToolDef[] {
const indexByName = new Map(registry.map(t => [t.name, t]));
// Also index by the un-prefixed op name (for friendlier allowed_tools entries).
const indexByShort = new Map(
registry.map(t => [t.name.replace(/^brain_/, ''), t]),
);
const seen = new Set<string>();
const picked: ToolDef[] = [];
for (const requested of allowedToolNames) {
const match = indexByName.get(requested) ?? indexByShort.get(requested);
if (!match) {
throw new Error(
`subagent allowed_tools references unknown tool "${requested}". ` +
`Known: ${[...indexByName.keys()].join(', ')}`,
);
}
if (seen.has(match.name)) continue;
seen.add(match.name);
picked.push(match);
}
return picked;
}
/** An absent trusted binding uses the registry; an explicit empty binding grants nothing. */
export function selectAllowedTools(registry: ToolDef[], allowed: unknown): ToolDef[] {
if (allowed === undefined) return registry;
if (!Array.isArray(allowed) || allowed.some(name => typeof name !== 'string' || name.trim() === '')) {
throw new Error('subagent allowed_tools must be an array of nonempty tool names');
}
return filterAllowedTools(registry, allowed);
}
/** Exported for unit tests (stable surface). */
export const __testing = {
sanitizeToolName,
paramsToInputSchema,
namespacedPutPageSchema,
ANTHROPIC_NAME_RE,
};