Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* request_tools operation cluster — pure move from operations.ts (v0.46.x
* tranche 3): the WP4 (T9) discovery + pull-based per-client surface-unlock
* op, its persist rate limiter (+ test seam), and the visibleOpsForCaller
* catalog filter. Op const stays module-private; `requestToolsOperations`
* below is spliced into the canonical `operations` array in ../operations.ts
* at the cluster's original position. Never import from '../operations.ts'
* here STATICALLY (cycle) — visibleOpsForCaller needs the assembled op list,
* so it loads it via dynamic import inside the call path (the verbs.ts house
* pattern: by the time a handler runs, operations.ts has finished loading).
*/
// WP4 (request_tools): the static imports below are runtime leaves
// relative to operations.ts (no import cycles back into it). The cyclic
// dependencies — src/mcp/surface.ts (→ brain-allowlist → operations),
// src/mcp/publish-gates.ts (→ operations), and the assembled `operations`
// array itself — are loaded via dynamic import inside the handler instead
// (the verbs.ts house pattern).
import { isUndefinedColumnError } from '../utils.ts';
import { suggestNearest } from '../levenshtein.ts';
import { hasScope, operationScopesAllowed } from '../scope.ts';
import { RateLimiter } from '../../mcp/rate-limit.ts';
import { writeSurfaceChangeAudit } from '../surface-audit.ts';
import type { Operation, OperationContext } from './contract.ts';
import { OperationError, opError } from './contract.ts';
import { hostFix, invalidParam } from './op-fix.ts';
/** stdio and legacy bearer tokens have no per-client surface row: the server's own start flag decides. */
const NO_CLIENT_SURFACE = 'no per-client surface on this transport; the server surface is set on the host with `gbrain serve --surface <verbs|starter|full>`';
import { opAllowedForBoundClient } from './context.ts';
// --- WP4 (T9): request_tools — discovery + pull-based per-client unlock ---
/**
* D14.5: per-client rate limit on the persist branch (~5 surface persists /
* hour / client). Module-level token bucket (bounded LRU — attacker-chosen
* client ids can't grow memory); `let` + reset seam so tests don't leak
* bucket state across files.
*/
let requestToolsPersistLimiter = new RateLimiter({ limit: 5, windowMs: 3_600_000, lruCap: 5_000 });
/** Test seam: fresh persist-rate-limit buckets. */
export function __resetRequestToolsPersistLimiterForTests(): void {
requestToolsPersistLimiter = new RateLimiter({ limit: 5, windowMs: 3_600_000, lruCap: 5_000 });
}
/**
* One-line catalog summary: the first sentence of an op description,
* capped. Non-contractual rendering — full schemas come from the
* `{tools: [...]}` branch.
*/
function firstSentenceOf(description: string): string {
const t = description.trim();
const m = t.match(/^.*?[.!?](?=\s|$)/);
const s = (m ? m[0] : t).trim();
return s.length > 160 ? `${s.slice(0, 157)}...` : s;
}
/**
* The set of ops VISIBLE to this caller (never leak hidden names — C8/
* amendment 11 class): bounded by the server ceiling (ops above it can
* never be served, so naming them would recreate listed-but-denied at the
* persist level), minus localOnly on network transports (stdio and the
* trusted local CLI keep them — D7), minus ops outside the caller's scopes
* (agent-callable carve-out per FOV-4), minus bound-client-fenced ops (same
* predicate as tools/list, ENG-3), minus publish-gated ops whose gate is off.
* Two DISTINCT caller axes here: localOnly visibility is the transport-
* LOCALITY axis (stdio pipe or trusted local CLI can call localOnly ops, D7),
* while publish gates are the owner-CONSENT axis and exempt ONLY
* ctx.remote === false (assertPublishEnabled + the advisor inline gate) —
* stdio dispatches remote:true, so its catalog subtracts gate-off ops or it
* advertises tools that deny at call time. A failed gate read hides the gated
* ops, fail-closed.
*/
async function visibleOpsForCaller(
ctx: OperationContext,
ceiling: 'verbs' | 'starter' | 'full',
): Promise<Operation[]> {
// The assembled op list lives in ../operations.ts, which spreads THIS
// module's array — so it must never be imported statically here. Loaded
// lazily instead (the verbs.ts house pattern); by the time any handler
// runs, operations.ts has finished evaluating.
const { operations } = await import('../operations.ts');
const { filterOpsForSurface } = await import('../../mcp/surface.ts');
// Locality axis: the stdio pipe or the local CLI (remote strictly false)
// CAN call localOnly ops, so hiding those would make the catalog dishonest.
const canSeeLocalOnly = ctx.transport === 'stdio' || ctx.remote === false;
// Consent axis: publish-gate enforcement exempts ONLY remote === false —
// stdio is remote:true, so it is gate-subject like every other agent caller.
const gateExempt = ctx.remote === false;
let gateDisabled: ReadonlySet<string> = new Set();
if (!gateExempt) {
try {
const { disabledOpsForPublishGates } = await import('../../mcp/publish-gates.ts');
gateDisabled = await disabledOpsForPublishGates(ctx.engine, ctx.config, { transport: ctx.transport });
} catch {
// Fail-closed: if the resolver can't even load, hide every gated op.
gateDisabled = new Set(operations.filter(o => o.publishGateKey).map(o => o.name));
}
}
// Auth-less transports (stdio) and grandfathered legacy bearer tokens
// (empty scopes array — that transport does no call-time scope checks
// either) skip scope filtering: for them the whole surface IS callable,
// so hiding by scope would make the catalog LESS honest, not more.
const scopes = ctx.auth?.scopes && ctx.auth.scopes.length > 0 ? ctx.auth.scopes : null;
return filterOpsForSurface(operations, ceiling).filter(op =>
(canSeeLocalOnly || !op.localOnly)
&& (ctx.remote === false || (scopes === null && !op.requiredScopes?.length)
|| operationScopesAllowed(scopes ?? [], op))
&& opAllowedForBoundClient(ctx.auth, op)
&& !gateDisabled.has(op.name),
);
}
/**
* Stdio branch of the {surface} call: widen this session's allow-set (the
* one tools/list and dispatch share), never past `--access read-only` or
* GBRAIN_MCP_FORCE_SURFACE, then answer with the newly allowed tools'
* schemas so a client that ignores `tools/list_changed` can call them by
* name. Nothing is written; a new session starts at the registered surface.
*/
async function widenStdioSession(ctx: OperationContext, requested: 'verbs' | 'starter' | 'full'): Promise<Record<string, unknown>> {
const session = ctx.stdioSurface!;
const { clampSurface, sessionWidenAllowed, surfaceWiderThan } = await import('../../mcp/surface.ts');
session.widenAllowed = await sessionWidenAllowed(ctx.engine, ctx.config);
const persistent = `For a lasting change, set GBRAIN_SURFACE=${requested} in the env of this harness's MCP server entry for gbrain (or re-register the server with --surface ${requested}) and start a new session.`;
if (!session.widenAllowed) {
throw opError('permission_denied',
'Session widening is off on this brain (mcp.allow_session_widen is false), so request_tools cannot add tools to this stdio session.',
`${persistent} The user can turn session widening back on with \`gbrain config set mcp.allow_session_widen true\`.`,
{ fix: hostFix(ctx, ['gbrain', 'config', 'set', 'mcp.allow_session_widen', 'true'],
`Turns stdio session widening back on (the brain owner turned it off). ${persistent}`) });
}
const target = clampSurface(requested);
if (!surfaceWiderThan(target, session.surface)) {
return { persisted: false, scope: 'session', surface: session.surface, widened: false,
note: target !== requested
? `GBRAIN_MCP_FORCE_SURFACE caps this server at '${target}', so this session stays at '${session.surface}'.`
: `This session already serves '${session.surface}', which includes everything in '${requested}'.` };
}
if (ctx.dryRun) return { persisted: false, scope: 'session', dry_run: true, surface: target, previous: session.surface };
const change = session.widen(target);
const added = new Set(change.added);
const { buildToolDefs } = await import('../../mcp/tool-defs.ts');
const { resolveStrictParamsMode } = await import('../../mcp/validate-params.ts');
const strictParams = (await resolveStrictParamsMode(ctx.engine, ctx.config)) === 'reject';
const visible = (await visibleOpsForCaller(ctx, target)).filter(op => added.has(op.name));
return {
persisted: false, scope: 'session', surface: target, previous: change.from,
tools: buildToolDefs(visible, { strictParams }),
note: `This session now serves '${target}' (tools/list_changed was sent). Call the new tools by name now; their schemas are above. A new session starts at the registered surface. ${persistent}`,
};
}
const request_tools: Operation = {
name: 'request_tools',
idempotent: false,
outputRedaction: 'no_stored_text',
description: 'More tools and params: no arguments lists your catalog; {tools: [names]} returns full schemas, every optional param included; {surface} widens it (per client or stdio session).',
area: 'discovery',
// FOV-4: callable by read OR agent scope — discovery for every token class.
agentCallable: true,
params: {
tools: {
type: 'array',
items: { type: 'string' },
description: 'Tool names to fetch.',
},
surface: {
type: 'string',
enum: ['verbs', 'starter', 'full'],
description: 'stdio: this session only.',
},
},
scope: 'read',
// D9: mutating because the persist branch writes oauth_clients.surface.
// The bound-client fence exempts it via BOUND_CLIENT_META_OPS (see the
// carve-out comment at opAllowedForBoundClient); the persist branch
// self-enforces ceiling + operator lock + scopes + rate limit.
mutating: true,
handler: async (ctx, p) => {
const { surfaceWiderThan, isMcpSurface, clampSurface } = await import('../../mcp/surface.ts');
// Unset ceiling (local CLI / direct dispatch) = 'full' — trusted-local
// callers were never surface-bounded.
const ceiling = ctx.surfaceCeiling ?? 'full';
// GBRA-449: {surface, tools} together runs the surface branch exactly as a surface-only call (its refusals
// included), then the descriptor branch against the resulting surface; surface_change carries the first answer.
if (p.surface !== undefined && p.tools !== undefined) {
const surfaceChange = await request_tools.handler(ctx, { surface: p.surface });
return { ...(await request_tools.handler(ctx, { tools: p.tools }) as Record<string, unknown>), surface_change: surfaceChange };
}
// ── persist branch ({surface}) ──────────────────────────────────────
if (p.surface !== undefined) {
const requested = p.surface as string;
if (!isMcpSurface(requested)) {
// Backstop for direct handler calls — MCP dispatch already rejects
// via the enum in validateParams (invalid_params naming the valid set).
throw invalidParam(ctx, 'request_tools', 'surface', 'surface must be one of: verbs, starter, full (got an unrecognized value)', { choices: ['verbs', 'starter', 'full'] });
}
const clientId = ctx.auth?.clientId;
if (!clientId && ctx.transport === 'stdio' && ctx.stdioSurface) return widenStdioSession(ctx, requested);
if (!clientId) {
// No per-token identity and no stdio session: a surface persist has nowhere to land.
return { persisted: false, reason: NO_CLIENT_SURFACE };
}
if (surfaceWiderThan(requested, ceiling)) {
const e = opError(
'permission_denied',
`surface '${requested}' is above this server's ceiling '${ceiling}' (D2: per-client surfaces narrow, never widen).`,
`The brain host's operator caps this server at surface '${ceiling}'; a wider surface needs that server restarted with \`gbrain serve --surface ${requested}\`. Tools outside '${ceiling}' stay unavailable on this connection until then.`,
{ fix: hostFix(ctx, ['gbrain', 'serve', '--surface', requested], 'The surface ceiling is a server start flag; only the host that runs the server can widen it.') },
);
e.detail = `ceiling=${ceiling}`; // amendment 4 key=value denial grammar; ENG-11 assign-after
throw e;
}
let rows: Record<string, unknown>[];
try {
rows = await ctx.engine.executeRaw(
`SELECT surface, surface_set_by FROM oauth_clients WHERE client_id = $1`,
[clientId],
);
} catch (err) {
if (isUndefinedColumnError(err, 'surface') || isUndefinedColumnError(err, 'surface_set_by')) {
// D5: a capability-negotiation op never returns internal_error for
// a pre-migration brain — report the gap and keep serving.
return { persisted: false, reason: 'migration pending' };
}
throw err;
}
if (rows.length === 0) {
// Legacy bearer tokens carry a clientId that is not an oauth_clients row.
return { persisted: false, reason: NO_CLIENT_SURFACE };
}
const current = rows[0] as { surface?: string | null; surface_set_by?: string | null };
const operatorLocked = () => {
const e = opError(
'permission_denied',
"this client's surface is operator-pinned and cannot be self-changed (amendment 19).",
`Ask the brain operator to change it: gbrain auth rescope-client ${clientId} --surface ${requested}`,
{ fix: hostFix(ctx, ['gbrain', 'auth', 'rescope-client', clientId, '--surface', requested],
'The operator pinned this client\'s surface; only the brain host\'s operator can change a pin.') },
);
e.detail = 'locked_by=operator';
return e;
};
if (current.surface_set_by === 'operator') throw operatorLocked();
// A dry-run preview exercises every denial above but must not consume
// the persist budget — the limiter meters actual writes only.
if (ctx.dryRun) {
return { persisted: false, dry_run: true, surface: requested, reason: 'dry_run' };
}
const rl = requestToolsPersistLimiter.check(clientId);
if (!rl.allowed) {
throw opError(
'rate_limited',
'surface persistence is rate-limited to ~5 changes per hour per client (D14.5).',
`Nothing changed. Call request_tools with this surface again after ~${rl.retryAfter ?? 60}s.`,
);
}
// Atomic re-check: a concurrent operator pin between the SELECT and
// this UPDATE must still win.
const updated = await ctx.engine.executeRaw(
`UPDATE oauth_clients SET surface = $1, surface_set_by = 'self'
WHERE client_id = $2 AND (surface_set_by IS DISTINCT FROM 'operator')
RETURNING client_id`,
[requested, clientId],
);
if (updated.length === 0) {
// Concurrent operator pin won the race: the denial must not consume
// the client's persist budget (the limiter meters actual writes).
requestToolsPersistLimiter.refund(clientId);
throw operatorLocked();
}
await writeSurfaceChangeAudit(ctx.engine, {
actor: clientId,
client_id: clientId,
old: (current.surface as string | null) ?? null,
new: requested,
via: 'request_tools',
});
return { persisted: true, surface: requested, note: 're-issue tools/list to see the new catalog' };
}
// A widenable stdio session lists what request_tools {surface} can add, not only what it serves now.
const session = ctx.transport === 'stdio' ? ctx.stdioSurface : undefined;
const catalogCeiling = session && session.widenAllowed && !session.readOnly ? clampSurface('full') : ceiling;
const visible = await visibleOpsForCaller(ctx, catalogCeiling);
const catalog = () => {
const groups = new Map<string, Array<{ name: string; one_line: string }>>();
for (const op of visible) {
// Area names are non-contractual grouping labels (amendment 22).
const area = op.area ?? 'other';
const bucket = groups.get(area) ?? [];
bucket.push({ name: op.name, one_line: firstSentenceOf(op.description) });
groups.set(area, bucket);
}
return [...groups.entries()]
.sort(([a], [b]) => a.localeCompare(b))
.map(([area, tools]) => ({ area, tools }));
};
const catalogNote = session
? 'Call request_tools {tools: ["name", ...]} for full schemas, or {surface: "starter"|"full"} to add those tools to this session (nothing is written).'
: 'Call request_tools {tools: ["name", ...]} for full schemas, or {surface: "starter"|"full"} to persist a wider tool surface for your OAuth client (within the server ceiling), then re-issue tools/list.';
// ── descriptor branch (D5: read-only) ───────────────────────────────
if (p.tools !== undefined) {
const requested = (p.tools as unknown[]).filter((t): t is string => typeof t === 'string');
// Registry definitions, not the surface-filtered ones: dispatch accepts a starter op's full-surface-only params, so the details path names them.
const { operations } = await import('../operations.ts');
const visibleSet = new Set(visible.map(o => o.name));
const byName = new Map(operations.filter(o => visibleSet.has(o.name)).map(o => [o.name, o]));
const picked: Operation[] = [];
const seen = new Set<string>();
for (const name of requested) {
if (seen.has(name)) continue;
seen.add(name);
const op = byName.get(name);
if (op) picked.push(op); // invisible names silently omitted (D5)
}
if (picked.length === 0) {
// D1: an empty or unknown-only list gets the catalog instead of `{tools: []}`.
// Suggestions come only from the caller-visible set and requested names are
// never echoed, so an existing-but-invisible name and a nonexistent one
// produce the same bytes (no existence oracle).
const visibleNames = visible.map(o => o.name);
const didYouMean = [...new Set([...seen].map(name => suggestNearest(name, visibleNames)).filter((n): n is string => n !== null))].sort();
return {
tools: [],
...(didYouMean.length ? { did_you_mean: didYouMean } : {}),
catalog: catalog(),
total_tools: visible.length,
note: `${seen.size ? 'None of the requested names is a tool this connection can call. ' : ''}${didYouMean.length ? 'The closest callable names are in did_you_mean; the' : 'The'} catalog lists every tool you can call. ${catalogNote}`,
};
}
const { buildToolDefs } = await import('../../mcp/tool-defs.ts');
const { resolveStrictParamsMode } = await import('../../mcp/validate-params.ts');
const strictParams = (await resolveStrictParamsMode(ctx.engine, ctx.config)) === 'reject';
if (ctx.revealTools) {
// A widenable session's catalog reaches past what it serves; only tools it can call now are listed.
const callable = catalogCeiling === ceiling ? visibleSet : new Set((await visibleOpsForCaller(ctx, ceiling)).map(o => o.name));
const reachable = picked.filter(o => callable.has(o.name)).map(o => o.name);
const outside = picked.filter(o => !callable.has(o.name)).map(o => `\`${o.name}\``);
if (reachable.length) ctx.revealTools(reachable);
if (!outside.length) return { tools: buildToolDefs(picked, { strictParams }), listed: true, note: 'These tools are now in your tool list (tools/list_changed was sent); call them directly.' };
return {
tools: buildToolDefs(picked, { strictParams }), listed: false,
note: `${reachable.length ? `${reachable.map(n => `\`${n}\``).join(', ')} are now in your tool list (tools/list_changed was sent). ` : ''}${outside.join(', ')} are outside this session's '${ceiling}' surface, so they are not listed and cannot be called yet: call request_tools {"surface":"full"} to add them to this session, then call them by name.`,
};
}
return { tools: buildToolDefs(picked, { strictParams }) };
}
// ── catalog branch (no args) ────────────────────────────────────────
return { catalog: catalog(), total_tools: visible.length, note: catalogNote };
},
};
export const requestToolsOperations: Operation[] = [request_tools];