Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* MEMORY_VERBS v1 + WP4 — MCP tool-surface modes.
*
* 'full' (default) — every operation, verbs included. Existing installs
* see no change; e2e tool-count assertions hold.
* 'starter' — the ~20-op daily-driver set (STARTER_OPS below):
* the seven frozen verbs + the fallback daily ops +
* whoami + the request_tools discovery meta-op. The
* answer to the "85-tool wall" consumer complaint.
* 'verbs' — EXACTLY the seven frozen protocol verbs (ops marked
* `verb: true`). The quickstart surface. Its semantics
* are frozen — 'starter' extends the ladder ABOVE it,
* never changes it.
*
* Enforcement is two-layer and fail-closed: ListTools advertises the filtered
* set, AND dispatchToolCall receives the same set as `allowedOps` so a hidden
* op stays uncallable even if a client guesses its name (tool-list filtering
* alone leaves dispatch resolving the global catalog — codex c2).
*
* Resolution: stdio GBRAIN_SURFACE > --surface flag > config `mcp_surface` >
* 'full' (resolveStdioSurface); `serve --http` ignores GBRAIN_SURFACE. Why
* default full: a bare `serve` keeps existing advanced tooling, and the
* registrations gbrain writes pin `REGISTRATION_SURFACE`
* (src/core/mcp-registration.ts) unless the user passes `--surface`.
*
* WP4 (D2 CEILING): on the OAuth HTTP transport the server-resolved surface is
* a CEILING, not the final answer — each request resolves
* `min(ceiling, client row surface ?? DCR/config default)` via
* `effectiveSurfaceForClient`, recomputed per request (amendment 20).
* `GBRAIN_MCP_FORCE_SURFACE` is the incident kill switch: it min()s in on top
* and can NEVER widen past the configured ceiling (FOV-6a) — widening requires
* an explicit `--surface` restart.
*/
import type { OperationMeta, ParamDef } from '../core/ops/contract.ts';
import type { Notice } from '../core/agent-output.ts';
import type { GBrainConfig } from '../core/config.ts';
import type { BrainEngine } from '../core/engine.ts';
import { VERB_NAMES } from '../core/verbs.ts';
import { opError } from '../core/ops/contract.ts';
import { BRAIN_TOOL_ALLOWLIST } from '../core/minions/tools/brain-tool-allowlist.ts';
import { flagValues } from '../core/direct-pool-profile.ts';
export type McpSurface = 'verbs' | 'starter' | 'full';
/** Widening order for the D2 ceiling math: verbs < starter < full. */
const SURFACE_RANK: Record<McpSurface, number> = { verbs: 0, starter: 1, full: 2 };
export function isMcpSurface(v: unknown): v is McpSurface {
return v === 'verbs' || v === 'starter' || v === 'full';
}
/** The narrower of two surfaces (verbs < starter < full). */
export function minSurface(a: McpSurface, b: McpSurface): McpSurface {
return SURFACE_RANK[a] <= SURFACE_RANK[b] ? a : b;
}
/** True when `a` is strictly wider than `b` (used for the ceiling deny). */
export function surfaceWiderThan(a: McpSurface, b: McpSurface): boolean {
return SURFACE_RANK[a] > SURFACE_RANK[b];
}
/**
* WP4 FOV-6b fallback for the daily-driver slice of STARTER_OPS.
*
* Provenance: the plan's STARTER_OPS derivation from the production
* `mcp_request_log` histogram (30d window, keyed by token_name) had NOT
* landed at implementation time (2026-08-13), so per FOV-6b this v1 set is
* the fallback: the reviewed subagent brain-tool allow-list
* (BRAIN_TOOL_ALLOWLIST — imported, never name-copied) plus the agent lane
* (`submit_agent` / `get_agent_job`, FOV-4 — agent-scope clients must not be
* stranded). Corrected later by `scripts/derive-starter-ops.ts` + the E3
* advisor drift check once the histogram pull lands.
*/
const FALLBACK_DAILY_OPS: readonly string[] = [
...BRAIN_TOOL_ALLOWLIST,
'submit_agent',
'get_agent_job',
'cancel_job',
];
/**
* The 'starter' surface membership set (WP4). Composed PROGRAMMATICALLY —
* the verb slice is a spread of VERB_NAMES (ENG-1: post-#4028 that is SEVEN
* verbs including context_pack/delta; never a hand-count), the daily slice
* is the FOV-6b fallback above, plus `whoami` (identity) and `request_tools`
* (the D4 discovery meta-op: listed on starter + full, never verbs).
*
* Membership is pinned by test/mcp-surface.test.ts: every name here must
* exist in `operations`, and allowedOpNames(verbs) ⊆ starter ⊆ full holds
* (monotonicity, ENG-1).
*/
export const STARTER_OPS: ReadonlySet<string> = new Set([
...VERB_NAMES,
...FALLBACK_DAILY_OPS,
'whoami',
'request_tools',
// [EV8] capture joins as a DIRECT literal — deliberately NOT via
// BRAIN_TOOL_ALLOWLIST (that would grant every minion subagent a new write
// tool and require the skillopt mutating-exclusion update). The plugin +
// starter connect lanes retire the "unknown tool: capture" FAQ, which only
// works if the starter surface actually lists it.
'capture',
// #5616: the small-change companion of put_page (a direct literal, like
// capture, so subagents do not gain a new write tool).
'edit_page',
'get_write_request', 'list_write_requests', 'cancel_write_request',
'list_skills', 'get_skill', 'list_brain_skillpack', 'get_skill_asset',
'join_brain', 'sync_brain_skills', 'leave_brain', 'put_skill', 'delete_skill',
// The dismissal for the coaching notices starter sessions receive (onboarding, features).
'mute_notice',
// GBRA-219: the per-conversation memory switch rides next to remember.
'memory_conversation_mode',
]);
/**
* The never-remove STARTER_OPS core: the seven frozen verbs, identity
* (`whoami`), discovery (`request_tools`), and the agent lane
* (`submit_agent`/`get_agent_job` — FOV-4: agent-scope clients must not be
* stranded). Usage-driven re-derivation (`scripts/derive-starter-ops.ts`)
* and the advisor drift check (collect-mcp-client-fit) both consume THIS
* set so "always included" has exactly one definition.
*/
export const ALWAYS_INCLUDED_STARTER_OPS: ReadonlySet<string> = new Set([
...VERB_NAMES,
'whoami',
'request_tools',
'submit_agent',
'get_agent_job',
// [EV8] capture is contract-bearing on the starter lanes (the retired FAQ
// points agents at it) — usage-driven re-derivation must never propose
// evicting it as a zero-usage newcomer.
'capture',
'get_write_request', 'list_write_requests', 'cancel_write_request',
'list_skills', 'get_skill', 'list_brain_skillpack', 'get_skill_asset',
'join_brain', 'sync_brain_skills', 'leave_brain', 'put_skill', 'delete_skill',
]);
/**
* Strict flag parser — unknown values reject loudly (parseStdioIdleTimeout pattern). `--surface=verbs` is the same flag
* (`flagValues`), and a repeated flag takes the narrowest value, so it never widens the ceiling.
*/
export function parseSurfaceFlag(args: string[]): McpSurface | null {
const values = flagValues(args, '--surface');
if (!values.length) return null;
for (const raw of values) {
if (!raw || raw.startsWith('--')) {
throw opError('invalid_params', `--surface requires a value: verbs | starter | full`, 'Pass --surface verbs, --surface starter or --surface full (default full).');
}
if (!isMcpSurface(raw)) {
throw opError('invalid_params', `Unknown --surface "${raw}". Use: verbs (the 7 memory verbs) | starter (the ~20 daily-driver ops) | full (all operations, default)`,
'Pass --surface verbs (the 7 memory verbs), --surface starter (the ~20 daily-driver ops) or --surface full (all operations, default).');
}
}
return (values as McpSurface[]).reduce(minSurface);
}
/**
* `--advertise`: the surface tools/list shows, narrower than what is callable.
* Registrations gbrain writes pass `--advertise verbs` (REGISTRATION_ADVERTISE);
* absent, `mcp.advertised_surface` decides.
*/
export function parseAdvertiseFlag(args: string[]): McpSurface | null {
const inline = args.find(a => a.startsWith('--advertise='));
const idx = args.indexOf('--advertise');
if (inline === undefined && idx < 0) return null;
const raw = inline !== undefined ? inline.slice('--advertise='.length) : args[idx + 1];
if (raw === undefined || raw.startsWith('--') || !isMcpSurface(raw)) {
throw opError('invalid_params', `gbrain serve --advertise takes verbs, starter or full${raw === undefined || raw.startsWith('--') ? '' : ` (got "${raw}")`}`,
'Run gbrain serve --advertise verbs (list the 7 memory verbs and request_tools), gbrain serve --advertise starter or gbrain serve --advertise full. Every tool the surface allows stays callable.');
}
return raw;
}
/**
* #4768: stdio access ceiling. `--access read-only` intersects the selected
* surface with operations that are read-scoped, non-mutating and need no
* capability scope, so tools/list, the capabilities resource, skill
* resources and dispatch all see one read-only set (`request_tools` is
* mutating, so discovery cannot widen it). It denies agent-requested
* mutations; owner maintenance (startup migrations, hook IPC banking) is a
* separate control. HTTP enforces per-token operation grants instead.
* `--access=read-only` is the same flag (`flagValues`); any read-only
* value wins, so a repeated flag never widens the ceiling.
*/
export type McpAccess = 'full' | 'read-only';
export function parseAccessFlag(args: string[]): McpAccess {
const values = flagValues(args, '--access');
if (values.some(raw => raw !== 'full' && raw !== 'read-only')) {
throw opError('invalid_params', '--access takes read-only or full (default full); see docs/mcp/ADMIN.md#read-only-stdio-serve',
'Pass --access read-only or --access full (default full).', { docs: 'docs/mcp/ADMIN.md#read-only-stdio-serve' });
}
return values.includes('read-only') ? 'read-only' : 'full';
}
export function isReadOnlyOperation(op: Pick<OperationMeta, 'scope' | 'mutating' | 'requiredScopes'>): boolean {
return op.scope === 'read' && op.mutating !== true && !op.requiredScopes?.length;
}
export type SurfaceSource = 'env' | 'flag' | 'config' | 'default';
/** How `serve` prints and `whoami` reports a surface source. */
export const SURFACE_SOURCE_LABEL: Record<SurfaceSource, string> = {
env: 'env GBRAIN_SURFACE', flag: '--surface', config: 'config', default: 'default',
};
/** --surface flag > config `mcp_surface` > 'full', with where the answer came from. */
export function resolveSurfaceWithSource(
flag: McpSurface | null,
config: Pick<GBrainConfig, 'mcp_surface'> | null | undefined,
): { surface: McpSurface; source: SurfaceSource; invalidEnv?: string } {
if (flag) return { surface: flag, source: 'flag' };
if (config && isMcpSurface(config.mcp_surface)) return { surface: config.mcp_surface, source: 'config' };
return { surface: 'full', source: 'default' };
}
/** Flag > config `mcp_surface` > 'full' (`serve --http`; stdio adds GBRAIN_SURFACE via resolveStdioSurface). */
export function resolveSurface(
flag: McpSurface | null,
config: Pick<GBrainConfig, 'mcp_surface'> | null | undefined,
): McpSurface {
return resolveSurfaceWithSource(flag, config).surface;
}
/**
* Stdio `serve`: GBRAIN_SURFACE > --surface > config `mcp_surface` > 'full',
* the plugin launcher's substitute-or-append semantics. An invalid env value
* never stops the server (that would end it before the handshake, where no
* agent sees it): it is ignored and returned as `invalidEnv`.
*/
export function resolveStdioSurface(
flag: McpSurface | null,
config: Pick<GBrainConfig, 'mcp_surface'> | null | undefined,
env: string | undefined = process.env.GBRAIN_SURFACE,
): { surface: McpSurface; source: SurfaceSource; invalidEnv?: string } {
if (env === undefined || env === '') return resolveSurfaceWithSource(flag, config);
if (isMcpSurface(env)) return { surface: env, source: 'env' };
return { ...resolveSurfaceWithSource(flag, config), invalidEnv: env };
}
export function filterOpsForSurface<T extends OperationMeta>(ops: T[], surface: McpSurface): T[] {
if (surface === 'full') return ops;
// FROZEN: 'verbs' is EXACTLY `op.verb === true` (MEMORY_VERBS v1) — starter
// extends the ladder above it and must never alter these semantics.
if (surface === 'verbs') return ops.filter(op => op.verb === true);
return ops.filter(op => STARTER_OPS.has(op.name)).map(starterParams);
}
/** Shared params a starter op leaves off its schema; the op keeps the shared definition, so every surface validates the same object. */
const STARTER_HIDDEN_PARAMS: Readonly<Record<string, ReadonlySet<string>>> = { remember: new Set(['expected_revision', 'force']) };
/** Starter ops advertise every param except the full-surface-only ones and their STARTER_HIDDEN_PARAMS. */
function starterParams<T extends OperationMeta>(op: T): T {
const hidden = STARTER_HIDDEN_PARAMS[op.name];
const keep = ([name, p]: [string, ParamDef]) => !p.fullSurfaceOnly && !hidden?.has(name);
const params = Object.entries(op.params);
if (params.every(keep)) return op;
return { ...op, params: Object.fromEntries(params.filter(keep)) };
}
/** The fail-closed allow-set handed to dispatchToolCall. */
export function allowedOpNames(ops: OperationMeta[], surface: McpSurface): ReadonlySet<string> {
return new Set(filterOpsForSurface(ops, surface).map(o => o.name));
}
// ---------------------------------------------------------------------------
// WP4 — kill switch + per-client (D2 ceiling) resolution
// ---------------------------------------------------------------------------
let warnedBadForceValue = false;
/**
* `GBRAIN_MCP_FORCE_SURFACE` — incident kill switch (amendment 21,
* env-above-config per the pace-mode precedent). NARROW-ONLY (FOV-6a):
* consumers min() it into the resolved surface, so it can clamp a
* misbehaving deployment down but can never widen past the configured
* ceiling. Unknown values are ignored with a one-time warn (ignoring can
* only leave the surface as configured — it never widens anything).
*/
export function readForceSurfaceEnv(
warn: (msg: string) => void = (msg) => process.stderr.write(`${msg}\n`),
): McpSurface | null {
const raw = process.env.GBRAIN_MCP_FORCE_SURFACE;
if (raw === undefined || raw === '') return null;
if (isMcpSurface(raw)) return raw;
if (!warnedBadForceValue) {
warnedBadForceValue = true;
warn(`[mcp] ignoring unknown GBRAIN_MCP_FORCE_SURFACE="${raw}" (use verbs | starter | full); surface stays as configured`);
}
return null;
}
/** min() the kill switch into a resolved surface. Narrow-only by construction. */
export function clampSurface(
surface: McpSurface,
warn?: (msg: string) => void,
): McpSurface {
const force = readForceSurfaceEnv(warn);
return force ? minSurface(surface, force) : surface;
}
// Warn-once-per-client bookkeeping for unknown oauth_clients.surface values
// (amendment 18). Bounded so attacker-controlled client ids can't grow it.
const warnedUnknownRowSurface = new Set<string>();
const WARNED_CLIENTS_CAP = 10_000;
/** Test seam: reset the warn-once caches. */
export function __resetSurfaceWarnCachesForTests(): void {
warnedUnknownRowSurface.clear();
warnedBadForceValue = false;
}
/**
* Parse an `oauth_clients.surface` row value (amendment 18). The column's
* value space is documented OPEN — deferred client tiers will write tier
* names into this same column — so an unrecognized value is IGNORED (falls
* back to server/config resolution) with a warn-log once per client, never
* an auth failure.
*/
export function resolveClientRowSurface(
raw: unknown,
clientId: string,
warn: (msg: string) => void = (msg) => process.stderr.write(`${msg}\n`),
): McpSurface | null {
if (raw === null || raw === undefined) return null;
if (isMcpSurface(raw)) return raw;
if (!warnedUnknownRowSurface.has(clientId)) {
if (warnedUnknownRowSurface.size >= WARNED_CLIENTS_CAP) warnedUnknownRowSurface.clear();
warnedUnknownRowSurface.add(clientId);
warn(`[mcp] client ${clientId} carries unrecognized oauth_clients.surface value; ignoring it and falling back to the server/config surface (rescope with: gbrain auth rescope-client ${clientId} --surface verbs|starter|full|clear)`);
}
return null;
}
/**
* Dual-plane resolution for `mcp.default_surface_dcr` — the surface applied
* to clients whose row surface is NULL (oauth_clients carries no DCR-origin
* marker, so the default applies to ALL null-surface OAuth clients; operators
* pre-seed important clients with `gbrain auth rescope-client <id> --surface
* full`). Legacy bearer tokens have no client row and keep the server ceiling
* (#9266). DB plane wins, file plane falls back, absent/unparseable on both =
* null (caller falls back to the server ceiling — pre-WP4 behavior). A
* failed DB read falls to the file plane; surface resolution must never take
* a request down.
*/
export async function resolveDefaultClientSurface(
engine: BrainEngine,
config: GBrainConfig | null | undefined,
): Promise<McpSurface | null> {
try {
const dbVal = await engine.getConfig('mcp.default_surface_dcr');
if (isMcpSurface(dbVal)) return dbVal;
if (dbVal != null) return null; // set but unrecognized → ignore (open value space)
} catch {
// Engine without a config table / transient error → file plane decides.
}
const fileVal = (config?.mcp as Record<string, unknown> | undefined)?.default_surface_dcr;
return isMcpSurface(fileVal) ? fileVal : null;
}
/**
* `mcp.advertised_surface`: which tools `tools/list` shows. The callable set
* (the ceiling: --surface > mcp_surface > full, per-client rows on HTTP) is
* unchanged, so a tool outside the advertised list is still callable and
* `request_tools` returns its schema. The ceiling stays the security boundary;
* the advertised list is a context-cost choice. DB plane wins, file plane
* falls back; unset or unrecognized = advertise the whole callable set.
*/
export async function resolveAdvertisedSurface(engine: BrainEngine | null, config: GBrainConfig | null | undefined, flag: McpSurface | null = null): Promise<McpSurface | null> {
if (flag) return flag;
if (engine) {
try {
const dbVal = await engine.getConfig('mcp.advertised_surface');
if (isMcpSurface(dbVal)) return dbVal;
if (dbVal != null) return null;
} catch { /* file plane decides */ }
}
const fileVal = (config?.mcp as Record<string, unknown> | undefined)?.advertised_surface;
return isMcpSurface(fileVal) ? fileVal : null;
}
/**
* `oauth_clients.surface_set_by` for a surface an install default wrote (the
* `gbrain agent register` presets and the harness grant profiles), not an
* operator: the client calls that surface but lists only the memory verbs and
* `request_tools`, like a stdio registration with `--advertise verbs`.
*/
export const INSTALL_SURFACE_SET_BY = 'install';
/**
* The advertised surface for one HTTP client. A client without its own
* surface gets the server's (`--advertise`, `mcp.advertised_surface`); one
* whose surface an install default wrote lists the verbs; one that chose its
* surface (an operator rescope, `request_tools {surface}`) lists it in full.
*/
export async function clientAdvertisedSurface(
auth: { surface?: unknown; surfaceSetBy?: string | null },
engine: BrainEngine | null, config: GBrainConfig | null | undefined, flag: McpSurface | null = null,
): Promise<McpSurface | null> {
if (auth.surface) return auth.surfaceSetBy === INSTALL_SURFACE_SET_BY ? 'verbs' : null;
return resolveAdvertisedSurface(engine, config, flag);
}
/**
* The tools to list: the callable set narrowed to the advertised surface
* (never wider). A narrowed list always keeps request_tools when it is
* callable: it is how an agent reaches the unlisted tools (the verbs surface
* itself has none).
*/
export function advertisedOps<T extends OperationMeta>(callable: T[], callableSurface: McpSurface, advertised: McpSurface | null): T[] {
if (!advertised || !surfaceWiderThan(callableSurface, advertised)) return callable;
const listed = new Set(filterOpsForSurface(callable, advertised).map(op => op.name));
return callable.filter(op => listed.has(op.name) || op.name === 'request_tools');
}
/**
* A stdio session's tool listing: the advertised surface, plus every tool
* `request_tools` described in this session (`reveal`), which notifies the
* client with tools/list_changed. Once the session widens (request_tools
* {surface}), the whole widened surface is listed. `mcp.advertised_surface` narrows only this
* listing; dispatch keeps the callable set.
*/
export function stdioToolListing(advertised: () => Promise<McpSurface | null>, session: { readonly surface: McpSurface },
server: { sendToolListChanged(): Promise<void> }) {
const revealed = new Set<string>();
const startSurface = session.surface;
const notify = () => { Promise.resolve(server.sendToolListChanged()).catch(() => { /* best-effort */ }); };
return {
async listed<T extends OperationMeta>(visible: T[]): Promise<T[]> {
// A session the agent widened with request_tools {surface} lists everything it asked for.
if (session.surface !== startSurface) return visible;
const listed = advertisedOps(visible, session.surface, await advertised());
return listed.length === visible.length ? visible : visible.filter(op => revealed.has(op.name) || listed.includes(op));
},
/** D2: whether tools/list shows this (callable) tool now. */
async isListed(op: OperationMeta): Promise<boolean> {
if (session.surface !== startSurface || revealed.has(op.name)) return true;
return advertisedOps([op], session.surface, await advertised()).length > 0;
},
reveal(names: string[]): void {
const before = revealed.size;
for (const name of names) revealed.add(name);
if (revealed.size > before) notify();
},
};
}
/**
* D2 CEILING resolution — the per-request effective surface on the OAuth
* HTTP transport:
*
* effective = clamp(min(server ceiling, client row surface ?? default ?? ceiling))
*
* where `clamp` folds in the GBRAIN_MCP_FORCE_SURFACE kill switch
* (narrow-only, FOV-6a). A verbs-pinned server with a `full` client row
* still serves verbs (pinned by test); a client can request a narrower
* surface than the ceiling and get it.
*/
export function effectiveSurfaceForClient(opts: {
ceiling: McpSurface;
/** Parsed row value (resolveClientRowSurface); null = no per-client surface. */
clientSurface: McpSurface | null;
/** mcp.default_surface_dcr resolution; null = unset (fall back to ceiling). */
defaultSurface: McpSurface | null;
warn?: (msg: string) => void;
}): McpSurface {
const requested = opts.clientSurface ?? opts.defaultSurface ?? opts.ceiling;
return clampSurface(minSurface(opts.ceiling, requested), opts.warn);
}
// ---------------------------------------------------------------------------
// Stdio session surface — one mutable allow-set per stdio server process
// ---------------------------------------------------------------------------
/**
* The stdio session's surface: tools/list, dispatch, the capabilities
* resource and `whoami` read the same object, so a `request_tools` widen is
* visible to all of them at once. Widening is session-scoped (nothing is
* written) and never passes `--access read-only`.
*/
export interface StdioSurfaceState {
surface: McpSurface;
readonly source: SurfaceSource;
readonly readOnly: boolean;
/** `mcp.allow_session_widen` as last resolved (boot, then each request_tools call). */
widenAllowed: boolean;
surfacedOps: OperationMeta[];
allowedOps: ReadonlySet<string> | undefined;
widen(to: McpSurface): { from: McpSurface; to: McpSurface; added: string[] };
}
export function createStdioSurfaceState(
ops: OperationMeta[],
init: { surface: McpSurface; source: SurfaceSource; readOnly: boolean; onWiden?: (change: { from: McpSurface; to: McpSurface; added: string[] }) => void },
): StdioSurfaceState {
const compute = (surface: McpSurface) => {
const surfacedOps = filterOpsForSurface(ops, surface).filter(op => !init.readOnly || isReadOnlyOperation(op));
const allowedOps = init.readOnly ? new Set(surfacedOps.map(op => op.name)) : surface === 'full' ? undefined : allowedOpNames(ops, surface);
return { surface, surfacedOps, allowedOps };
};
const state: StdioSurfaceState = {
source: init.source,
readOnly: init.readOnly,
widenAllowed: true,
...compute(init.surface),
widen(to) {
const from = state.surface;
const before = new Set(state.surfacedOps.map(op => op.name));
Object.assign(state, compute(to));
const change = { from, to, added: state.surfacedOps.filter(op => !before.has(op.name)).map(op => op.name) };
init.onWiden?.(change);
return change;
},
};
return state;
}
/** `mcp.allow_session_widen` (default true): DB plane, then the file plane (file only when `engine` is null). */
export async function sessionWidenAllowed(engine: BrainEngine | null, config: GBrainConfig | null | undefined): Promise<boolean> {
const off = (v: unknown) => v === false || (typeof v === 'string' && /^(false|0|off|no)$/i.test(v.trim()));
try {
const dbVal = engine ? await engine.getConfig('mcp.allow_session_widen') : null;
if (dbVal != null) return !off(dbVal);
} catch { /* the file plane decides */ }
return !off(config?.mcp?.allow_session_widen);
}
/** The once-per-process `surface_env_invalid` info notice for an ignored GBRAIN_SURFACE value. */
export function surfaceEnvInvalidNotice(raw: string, served: McpSurface, source: SurfaceSource): Notice {
return {
code: 'surface_env_invalid', kind: 'info',
why: `GBRAIN_SURFACE="${raw}" is not a tool surface (use verbs, starter or full), so this server ignored it and serves '${served}' (source: ${SURFACE_SOURCE_LABEL[source]}).`,
user_message: `The gbrain MCP server's GBRAIN_SURFACE setting ("${raw}") is not valid; it takes verbs, starter or full. Can you fix it in the env of your agent app's MCP server entry for gbrain?`,
};
}