Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Foundation contract for the operations layer (pure move from
* src/core/operations.ts): the error envelope (ErrorCode / OperationError /
* verbError), the shared param/logger/auth/context types, and the Operation
* interface that every op declaration conforms to. operations.ts re-exports
* this entire surface, so existing importers are unchanged.
*/
import type { WriteInference } from './write-inference.ts';
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { MEMORY_VERBS_VERSION } from '../verbs.ts';
import { publicWriteReceipt, type WriteErrorCode, type WriteReceipt } from '../persistence/types.ts';
// Type-only: this module sits in the PGLite snapshot-schema import closure
// (via persistence/digest.ts), so it must not pull agent-output's runtime
// graph (version.ts, the DB classifier) in. agent-output registers the wire
// renderer below when it loads.
import type { Action, Notice } from '../agent-output.ts';
import type { RegistryCode } from '../error-registry.ts';
import type { WriteAuthority } from '../persistence/model.ts';
import type { TrustTier } from '../trust/tier.ts';
import type { StdioSurfaceState } from '../../mcp/surface.ts';
import type { GuestChannels } from '../guests/admission.ts';
/** Agent contract v1: the wire renderer for `fix`/`notices` in toJSON(), registered by agent-output.ts on load. */
interface OperationErrorWireRenderer { fix(a: Action): unknown; notice(n: Notice): unknown }
let wireRenderer: OperationErrorWireRenderer | null = null;
/** @internal agent-output.ts only. Unregistered (agent-output never loaded) → the stored Action is emitted as-is. */
export function __registerOperationErrorRenderer(r: OperationErrorWireRenderer): void { wireRenderer = r; }
// --- Types ---
/**
* v0.31 (eD6 / eE7): ErrorCode is now an OPEN union via the
* `(string & {})` autocomplete-friendly hack. Downstream consumers (e.g.
* gbrain-evals) get autocomplete on the named codes AND remain TS-forward-
* compatible when gbrain adds new codes in future releases. This shape is
* the standard Anthropic-API/OpenAI-API pattern.
*
* v0.31 added: 'rate_limited', 'extraction_failed', 'fact_not_found'.
*/
export type ErrorCode =
| WriteErrorCode
| 'page_not_found'
| 'invalid_params'
| 'embedding_failed'
| 'storage_error'
| 'bucket_not_found'
| 'database_error'
| 'permission_denied'
| 'unknown_transport' // v0.28.1: whoami fail-closed for ambiguous transport
| 'rate_limited' // v0.31: gateway rate-limit upstream
| 'extraction_failed' // v0.31: facts extractor failed (refusal, parse, abort)
| 'fact_not_found' // v0.31: forget_fact / recall on unknown id
// MEMORY_VERBS v1 protocol codes (frozen — docs/protocol/MEMORY_VERBS_v1.md).
// Coarse on purpose: codes are for branching (configure/retry vs caller bug
// vs server bug); the freeform `detail` field carries specifics.
| 'not_found' // unknown resource. Verb-level (forget: unknown fact id) AND
// get_agent_job's uniform foreign-or-missing envelope (anti-enumeration:
// a caller cannot distinguish another client's job from a nonexistent id)
| 'scope_denied' // verb-level: OAuth scope / trust-boundary refusal
| 'provenance_required' // remember: provenance missing or empty
| 'unavailable' // a required dependency cannot serve (no API key, gateway down, model refusal)
| 'budget_unsatisfiable' // RESERVED in v1 — schema-listed, never returned
| 'embedding_budget_below_worst_case' // #5680: migration cap below its worst-case authorization; refused before any change
// eslint-disable-next-line @typescript-eslint/ban-types
| (string & {}); // OPEN union for forward-compat (eE7 / D13)
/** `withdrawn` on a `fact_withdrawn` refusal: `subject` is the entity slug, or `all_entities` for a claim forgotten without one. */
export interface WithdrawnDetail { at: string; subject: string; visibility: 'world' | 'private' }
export class OperationError extends Error {
/**
* MEMORY_VERBS v1: verb handlers set `protocolVersion` (=1) and may set
* `detail` (freeform specifics, e.g. which dependency failed). Both are
* additive — non-verb ops never set them and their envelopes are unchanged
* (undefined keys drop out of JSON.stringify).
*/
public detail?: string;
public protocolVersion?: number;
public writeRequest?: WriteReceipt;
public writeError?: WriteErrorCode;
/** #6989: the request ID of a write that may have committed although its reply was not delivered (`response_too_large`); never invented for a read. */
public requestId?: string;
/** Agent contract v1 (A1): which cause, when one code covers several. */
public reason?: string;
/** Agent contract v1: why it happened, for the agent to explain and weigh. */
public why?: string;
/** Agent contract v1: the one next step. Rendered (`next`, `command`) only at serialization. */
public fix?: Action;
/** Site-level override of the code's class-derived `retryable` (#6278: `owner_unavailable` / `host_mismatch` is never worth a retry). */
public retryable?: boolean;
/** Agent contract v1: advice that rides the error (rendered into the envelope's `notices`). */
public notices?: Notice[];
/** #6188 (D16, D18): a fence refusal's location and its blocking issues; location and class only, never a cell value. */
public fence?: Record<string, unknown>;
public fenceIssues?: Array<Record<string, unknown>>;
/** A `fact_withdrawn` refusal's withdrawal: when and for which subject the exact claim was forgotten. Absence carries no meaning. */
public withdrawn?: WithdrawnDetail;
/** A write-grant refusal's writable sources: only ids the caller's own grant lets it write, never another source (GBRA-200). */
public writableSourceIds?: string[];
/** #6643: a managed-sync refusal's owner-side classification (knock-on root, cursor fence snapshot); stored as the receipt's error_detail, never in the envelope. */
public syncRefusal?: Record<string, unknown>;
/** Set to 1 by opError(); toJSON() emits `contract_version` only when set. */
public contractVersion?: 1;
/**
* Canonical registry code when this site keeps a frozen legacy `error`
* value (A1 frozen pairs, e.g. `error: invalid_params`, `code: not_found`).
*/
public canonical?: RegistryCode;
/**
* Agent contract v1 (B4): the journal row's own fields on a write-receipt
* error, never serialized. toAgentError fills the registry's fix template
* from them and picks the principal-correct receipt channel.
*/
public receiptFields?: { operation: string; source_id: string; slug: string | null; principal_kind: string; principal_id: string };
constructor(
public code: ErrorCode,
message: string,
public suggestion?: string,
public docs?: string,
) {
super(message);
this.name = 'OperationError';
}
/**
* The canonical registry code (`code` on the wire); `this.code` stays the
* frozen `error` value. Registry-wide legacy aliases are applied by
* toAgentError / the thin client (canonicalCodeFor), not here.
*/
get canonicalCode(): string {
return this.canonical ?? this.code;
}
/**
* The explicit escape from opError()'s required suggestion: a refusal whose
* next step genuinely cannot be named at the throw site. `reason` is
* required so the registry default fix can still be selected.
*/
static bare(code: RegistryCode, message: string, reason: string): OperationError {
const e = new OperationError(code, message);
e.reason = reason;
e.contractVersion = 1;
return e;
}
toJSON() {
return {
error: this.code,
code: this.canonicalCode,
message: this.message,
suggestion: this.suggestion,
docs: this.docs,
detail: this.detail,
protocol_version: this.protocolVersion,
...(this.writeRequest ? { write_request: publicWriteReceipt(this.writeRequest) } : {}),
...(this.requestId ? { request_id: this.requestId } : {}),
...(this.writeError ? { write_error: this.writeError } : {}),
...(this.reason !== undefined ? { reason: this.reason } : {}),
...(this.why !== undefined ? { why: this.why } : {}),
...(this.fix ? { fix: wireRenderer ? wireRenderer.fix(this.fix) : this.fix } : {}),
...(this.notices?.length ? { notices: this.notices.map(n => wireRenderer ? wireRenderer.notice(n) : n) } : {}),
...(this.fence ? { fence: this.fence } : {}),
...(this.fenceIssues?.length ? { fence_issues: this.fenceIssues } : {}),
...(this.withdrawn ? { withdrawn: this.withdrawn } : {}),
...(this.writableSourceIds ? { writable_source_ids: this.writableSourceIds } : {}),
...(this.contractVersion !== undefined ? { contract_version: this.contractVersion } : {}),
};
}
}
export interface OpErrorOpts {
reason?: string;
why?: string;
fix?: Action;
docs?: string;
detail?: string;
/** Overrides the class-derived `retryable` on the envelope for this site. */
retryable?: boolean;
/**
* The frozen v1 `error` wire value when this site historically threw a
* different code (A1 frozen pairs). `error` keeps this value; `code` is the
* canonical registry code passed to opError().
*/
legacy_error?: string;
}
/**
* Agent contract v1 error constructor (mirrors verbError): `suggestion` is
* positional and required. Use `OperationError.bare()` only when no next step
* can be named at the throw site.
*/
const notAdmittedWrites = new WeakSet<OperationError>();
/**
* A write refusal raised after its admission transaction rolled back, so nothing was admitted: the agent contract's
* safe-recovery rule (only idempotent mutations read retryable) gives way for it. Only write admission marks errors.
*/
export function markNotAdmitted(error: OperationError): OperationError { notAdmittedWrites.add(error); return error; }
export function provesNotAdmitted(error: unknown): boolean { return error instanceof OperationError && notAdmittedWrites.has(error); }
export function opError(code: RegistryCode, message: string, suggestion: string, opts: OpErrorOpts = {}): OperationError {
const e = new OperationError(opts.legacy_error ?? code, message, suggestion, opts.docs);
if (opts.legacy_error !== undefined) e.canonical = code;
if (opts.reason !== undefined) e.reason = opts.reason;
if (opts.why !== undefined) e.why = opts.why;
if (opts.fix !== undefined) e.fix = opts.fix;
if (opts.detail !== undefined) e.detail = opts.detail;
if (opts.retryable !== undefined) e.retryable = opts.retryable;
e.contractVersion = 1;
return e;
}
/**
* CLI→MCP gap-closure wave (ENG-E2) — shared relation-missing guard for the
* telemetry ops (get_job_stats, cache_stats, search_stats, search_tune).
* Older brains that predate a feature's tables raw-error with Postgres 42P01
* ("relation … does not exist") / PGLite's equivalent; every telemetry op
* must degrade to the SAME actionable 'unavailable' envelope instead — one
* helper, never four inline copies.
*/
export async function withRelationGuard<T>(fn: () => Promise<T>, what: string): Promise<T> {
try {
return await fn();
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
if (/relation .* does not exist|no such table/i.test(msg)) {
// The cause is not knowable here (pending migrations, or a dropped table), so the fix is the
// registry's diagnostic read (doctor on the brain host); the prose names no other command and the
// envelope appends the rendered fix, so suggestion and fix always agree.
throw opError(
'unavailable',
`${what} is unavailable on this brain: a required table is missing.`,
'The brain is missing a table this gbrain expects (usually pending schema migrations). Doctor on the brain host reports what is missing and the command that repairs it.',
{ reason: 'schema_missing' },
);
}
throw err;
}
}
/**
* MEMORY_VERBS v1 error constructor. Every verb error carries a populated
* `suggestion` (problem + cause + fix — agents read it and self-correct;
* conformance asserts non-empty) and `protocol_version: 1`.
*/
export function verbError(
code: ErrorCode,
message: string,
suggestion: string,
detail?: string,
): OperationError {
const e = new OperationError(code, message, suggestion);
e.protocolVersion = MEMORY_VERBS_VERSION;
if (detail !== undefined) e.detail = detail;
return e;
}
export interface ParamDef {
type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
required?: boolean;
description?: string;
default?: unknown;
enum?: string[];
/**
* GST-927: the valid range's lower bound (inclusive / exclusive). Read by normalizeOptionalParams and carried in the
* operation manifest, never in the tools/list schema. Only on read ops (test/tool-args-empty-optional-sol.test.ts): on an optional param whose range excludes 0, a 0 reads as omitted. Declare it only where 0 refuses.
*/
minimum?: number;
exclusiveMinimum?: number;
/** GST-927: on an optional array param, `[]` reads as omitted when this is at least 1. Not in tools/list. */
minItems?: number;
/** GST-927: a flag that acts only when true, so an optional `false` reads as omitted. Not in tools/list. */
actsWhenTrue?: boolean;
/** GST-927: the param has no effect without this one, so any value of it reads as omitted when that param is absent. Not in tools/list. */
appliesWith?: string;
items?: ParamDef;
/** Object members (O-DX-3); a member with `required: true` lands in the schema's `required`. */
properties?: Record<string, ParamDef>;
/** Advertised on the full MCP surface only (keeps the starter tool list inside its size budget). */
fullSurfaceOnly?: boolean;
/** An object param the CLI takes as repeated `--flag key=value` (`key=a,b` is a list); MCP passes the object. */
cliKeyValue?: boolean;
/** An object window the CLI also takes as `N-M` (inclusive) or `N`: the [start, length] member names. */
cliRange?: readonly [string, string];
}
export interface Logger {
info(msg: string): void;
warn(msg: string): void;
error(msg: string): void;
}
export interface AuthInfo {
token: string;
clientId: string;
/** Durable, verifier-derived identity. Never infer this from a display name or request data. */
principal?: { kind: 'oauth_client' | 'legacy_token'; id: string };
/**
* GBRA-218: the live member this credential is bound to and its groups, joined by the verifier
* (null = unbound). Undefined when no verifier joined it; src/core/access/caller.ts then looks the
* binding up from `principal` (fail closed). Never set from request data.
*/
member?: { id: string; groups: string[] } | null;
/** GBRA-218: the stored `may_act_for` audience list (shared agents, PR B); stored and reported only. */
mayActFor?: string[] | null;
/**
* GST-363: the brain operator let this credential read unscoped on purpose (`reads_unscoped` is set, gbrain auth
* rescope --reads-unscoped --yes). Undefined when no verifier read it; access/requester-scope.ts then looks it up.
*/
readsUnscoped?: boolean;
/** GST-363: when the credential was created, epoch seconds (access_tokens.created_at, oauth_clients.client_id_issued_at); null = unknown, which counts as old. */
createdAt?: number | null;
/**
* GST-359 C1: the live right to name the person a call serves (x-qm-actor), joined by the verifier: the system and
* the operations an attested call may run, and (GST-1158 F3) how it reads named sources. Null when the credential holds none, is bound to a member, or (an OAuth
* client) its token did not come from the client-credentials grant. Undefined when no verifier joined it.
*/
attest?: { system: string; ops: string[]; sources: string[] | null; read?: 'person' | 'scope' } | null;
/**
* Human-readable agent name resolved at token-verification time.
* For OAuth clients this is `oauth_clients.client_name`; for legacy
* bearer tokens it is `access_tokens.name`. Threading this through
* AuthInfo eliminates a per-request DB roundtrip in the /mcp handler
* (was: SELECT client_name FROM oauth_clients WHERE client_id = ?
* on every request — see PR #586 review note D14=B).
*/
clientName?: string;
scopes: string[];
/** Operator-approved operation snapshot; NULL/undefined keeps legacy grants. */
allowedOperations?: string[] | null;
issuedScopes?: string[];
sourceActive?: boolean;
boundTools?: string[] | null;
boundSourceId?: string | null;
boundBrainId?: string | null;
delegatedNamespace?: 'prefixes' | 'job';
boundMaxConcurrent?: number;
budgetUsdPerDay?: string | null;
grantRevision?: number;
grantProfile?: string | null;
grantRepairReasons?: string[];
/** The client's stored access-token lifetime override (`oauth_clients.token_ttl`); null = server default. */
tokenTtlSeconds?: number | null;
delegatedSlugPrefixes?: string[] | null;
/** Missing grant projection on a profile client is fail-closed. */
grantProjectionDegraded?: boolean;
expiresAt?: number;
/**
* v0.34.1 (#861, D2): the source the calling OAuth client is scoped
* to (write authority). Sourced from `oauth_clients.source_id` at
* token-verification time. The HTTP transport ALSO threads this
* value into `OperationContext.sourceId` at the same site so op
* handlers can consume it via the canonical `ctx.sourceId` (D2
* dual-write decision — identity surface symmetric with
* `allowedSources` below).
*
* Undefined for legacy bearer tokens that predate v0.34.1 and for
* clients that haven't been scoped yet. Migration v60 backfills
* NULL → 'default' for pre-existing rows so this field is populated
* on the upgrade path; brand-new public-client registrations may
* still leave it null until an operator explicitly scopes via
* `gbrain auth scope-client`.
*/
sourceId?: string;
/**
* #3242 (serve --http parity): distinguishes an operator-set source scope
* from the historical no-grant 'default' floor. `false` ONLY for a legacy
* bearer token whose `access_tokens.permissions.source_id` is absent —
* the one case whose unqualified reads may widen to the federated set.
* `true` (or undefined, e.g. OAuth clients) never widens. Mirrors
* `AuthResult.hasSourceGrant` in `src/mcp/http-transport.ts`.
*/
hasSourceGrant?: boolean;
/**
* v0.34.1 (#876): array of source ids this OAuth client may READ
* from (federation). Sourced from `oauth_clients.federated_read`.
* Independent of `sourceId` (write authority): a "WeCare L3 dept"
* client can write to `source_id='dept-x'` while reading the union
* of `['dept-x', 'wecare-parent', 'shared']`.
*
* Empty array `[]` means "no federated reads beyond `sourceId`".
* Undefined means "the post-v60 backfill hasn't populated this row
* yet" — engines fall back to scalar `sourceId` filtering in that
* case (back-compat).
*/
allowedSources?: string[];
/**
* Per-token allow-list for the holder field on `takes`, populated at
* token-verification time from `access_tokens.permissions.takes_holders`
* for legacy bearer tokens (via `parseTakesHoldersAllowList` in
* `src/core/legacy-token-scope.ts`). The HTTP transport threads this into
* `OperationContext.takesHoldersAllowList` (documented below).
*
* `[]` is an explicit deny-all grant and is PRESERVED (never collapsed).
* `undefined` means the token row carries no array grant — OAuth clients
* have no per-client storage yet (see TODOS.md) — and consumers apply the
* fail-closed `['world']` default at the dispatch site.
*
* Rides the same `as CoreAuthInfo as SdkAuthInfo` cast as `sourceId` /
* `allowedSources` above.
*/
takesHoldersAllowList?: string[];
/**
* v0.42.72.0: slug-prefix WRITE binding from
* `oauth_clients.bound_slug_prefixes`, threaded at token-verification
* time (same JOIN as sourceId/allowedSources — no per-op roundtrip).
* When present, every direct slug-mutating write op is fenced to slugs
* under one of these prefixes via `enforceClientSlugFence` — the same
* plain-startsWith semantics (and the same fail-closed empty-array
* posture) as submit_agent's bound_slug_prefixes check, so one column
* means one thing everywhere it's read. Closes the write-side half of
* shared-source isolation: reads were SQL-fenced via `allowedSources`,
* but same-source writes were folder-convention-only.
*
* Undefined = client has no binding, or the brain predates the
* bound_slug_prefixes column → no fence (unbound clients keep
* full-source write authority, back-compat).
*/
boundSlugPrefixes?: string[];
/**
* Set when token verification could not read `bound_slug_prefixes` (the
* projection degraded on a brain missing an OAuth column). The fence can't
* distinguish "no binding" from "binding unknown" otherwise, so writes are
* refused rather than silently unfenced. Read/auth degradation is
* unaffected — this axis alone fails closed.
*/
fenceProjectionDegraded?: boolean;
/**
* WP4 (D2): per-client tool surface from `oauth_clients.surface`, threaded
* at token-verification time (same JOIN as sourceId/allowedSources). The
* serve-http transport resolves the request's effective surface as
* `min(server ceiling, this ?? config default)` — the row can narrow, never
* widen. Value space is OPEN (amendment 18: future client tiers write tier
* names into the same column); unrecognized values are ignored at
* resolution with a warn-log once per client. Undefined = column NULL,
* projection degraded, or the brain predates migration v127.
*/
surface?: string;
/**
* #5575 (CEO-18): the token's read floor (`oauth_clients.min_trust` /
* `access_tokens.min_trust`), set only by the local CLI (`gbrain auth create
* --min-trust`, `gbrain auth set-min-trust`). Every read op applies
* max(this floor, the caller's `min_trust` param), so a client can raise it
* but never lower it. Undefined = no floor (or a brain before the column).
*/
minTrust?: TrustTier;
/**
* GBRA-156: the grant's `private_pages: granted_sources` axis, set at token
* verification from the live row. `sources` are the sources the grant names
* explicitly (`privatePagesSources`); MCP dispatch makes them the
* private-readable set of each non-mutating call. Undefined = `none`.
*/
privatePages?: { mode: 'granted_sources'; sources: string[] };
/**
* GBRA-575: the grant's `private_facts: granted_sources` axis, set at token
* verification from the live row, with the same explicitly named sources.
* MCP dispatch makes them the private-fact sources of each non-mutating call
* (CallerAccess.privateFactSources). Undefined = `none`.
*/
privateFacts?: { mode: 'granted_sources'; sources: string[] };
/** Current transport ceiling applied to this authenticated request. */
effectiveSurface?: 'verbs' | 'starter' | 'full';
/**
* WP4 (amendment 19) — who set `surface`: 'operator' (rescope CLI/admin
* endpoint; request_tools persist may NOT override it), 'self'
* (request_tools persist), or 'dcr_default'. Undefined when surface is
* unset or the projection degraded.
*/
surfaceSetBy?: string;
}
/**
* Transport a verified caller authenticated through. The verifier-set
* `principal` is authoritative; the `gbrain_cl_` client-id prefix is only a
* fallback for AuthInfo built without one.
*/
export function authTransport(auth: AuthInfo): 'oauth' | 'legacy' {
if (auth.principal) return auth.principal.kind === 'oauth_client' ? 'oauth' : 'legacy';
return auth.clientId.startsWith('gbrain_cl_') ? 'oauth' : 'legacy';
}
export interface OperationContext {
engine: BrainEngine;
config: GBrainConfig;
logger: Logger;
dryRun: boolean;
/**
* OAuth auth info (v0.8+). Present when the caller authenticated via OAuth 2.1
* through `gbrain serve --http`, or a remote-owned delegated worker tool.
* Worker auth carries the current read grant; explicit tool bindings grant
* delegated operations independently of the parent's direct read/write scopes.
*/
auth?: AuthInfo;
/**
* True when the caller is remote/untrusted (MCP over stdio/HTTP, or any agent-facing entry point).
* False for local CLI invocations by the owner of the machine.
*
* Security-sensitive operations (e.g., file_upload) tighten their filesystem
* confinement when remote=true and allow unrestricted local-filesystem access
* when remote=false.
*
* REQUIRED as of the F7b hardening — the type system is the first line of defense.
* Every transport (CLI / stdio MCP / HTTP MCP / subagent dispatcher) sets this
* explicitly. Consumers still treat anything that isn't strictly `false` as
* remote/untrusted (defense in depth in case the type is bypassed via cast).
*/
remote: boolean;
/**
* #6696 (A5): who this caller's writes are for, set only by trusted host-side entry points (the CLI, the MCP
* transports). Unset is `background`; it is never derived from `remote` (persistence/admission-origin.ts).
*/
admissionOrigin?: import('../persistence/admission-origin.ts').AdmissionOrigin;
/** The caller's self-declared agent label, read by an HTTP transport from X-Gbrain-Agent-Label (persistence/attribution.ts). Unverified text, never authority. */
agentLabel?: string;
/**
* Transport marker for auth-less remote surfaces (#1061). The stdio MCP
* dispatch sets 'stdio' — it is deliberately `remote: true` (agent-facing,
* untrusted) but has no per-token auth (local pipe), so identity ops like
* whoami need a way to distinguish "known auth-less transport" from "a
* transport bug forgot to thread ctx.auth". Trust decisions MUST NOT key
* off this field — only `ctx.remote === false` grants trust. It IS the
* transport-LOCALITY axis: localOnly ops dispatch on 'stdio' (a local
* pipe with the operator's own filesystem) and are denied on 'http'
* (network transports), independent of the remote trust flag.
*/
transport?: 'stdio' | 'http';
/**
* Largest request frame this connection reads, in bytes, set by the transport that built the context (legacy HTTP:
* GBRAIN_HTTP_MAX_BODY_BYTES; OAuth /mcp: the SDK's 4 MiB; stdio: its message buffer). Sizes upload parts
* (persistence/page-upload.ts partMaxFrameBytes); never a trust input.
*/
inboundFrameBytes?: number;
/**
* WP2/D3: response-meta side channel. Handlers that compute out-of-band
* result metadata (retrieval degradation, strict-mode warnings) publish it
* here under a namespaced top-level key; the MCP dispatch layer merges the
* collected keys into `ToolResult._meta` (one producer per key — see
* docs/protocol/MCP_META_CHANNELS.md). Unset on CLI/local dispatch paths,
* which render the same meta directly; emissions are always optional-chained.
*/
emitResponseMeta?: (key: string, value: unknown) => void;
/**
* Agent contract v1 (A6): model-visible advice. MCP dispatch renders each
* notice as a prefixed extra text block plus `_meta.gbrain_notices` on
* success, and into the error envelope's `notices` key on failure. Unset
* on callers that have no notice channel; producers call it optionally.
*/
emitNotice?: (n: Notice) => void;
/**
* Wakeshift (docs/guides/wakeshift.md): the MCP caller as the transport saw it, which Wakeshift uses to tell agent
* programs apart: `clientInfo.name` (stdio) or the OAuth `client_name` (HTTP), the HTTP User-Agent and the request's
* `_meta`. Set by the MCP transports only, never from tool arguments; shape only, never authority.
*/
mcpCaller?: { client?: string; userAgent?: string; meta?: Record<string, unknown> };
/** Wakeshift: a handler's addition, rendered as the result's last text block plus `_meta` keys. A credential: never log it. */
emitToolTail?: (tail: { text?: string; meta?: Record<string, unknown> }) => void;
/**
* WP4 (D2): the SERVER surface ceiling for this transport (force-clamped),
* threaded by the MCP dispatch layer. Consumed by `request_tools`: the
* catalog never names ops above the ceiling, and the persist branch
* rejects widening past it with a machine-readable denial
* (`detail: "ceiling=<surface>"`). Unset (local CLI / direct dispatch) is
* treated as 'full'.
*/
surfaceCeiling?: 'verbs' | 'starter' | 'full';
/**
* GBRA-218 local `--as <member>`: the member identity a trusted local read previews. Set only by the
* CLI with `applyRemoteReadPolicy`; `remote` stays false, so upload confinement and write trust are unchanged.
*/
accessIdentity?: readonly string[];
/** GBRA-218: page reads apply the remote read policy (readers and privacy) although the caller is local (`--as`). */
applyRemoteReadPolicy?: boolean;
/** The stdio session's surface (stdio MCP only): `request_tools` widens it for this session, `whoami` reports it. */
stdioSurface?: StdioSurfaceState;
/**
* GST-363: the member this stdio server was started with (`gbrain serve --stdio-member <id>`, written into one
* harness's own MCP entry). Set only by the stdio server from its process argv, never from a request; it wins over
* config mcp.stdio_member, and a named member that is not enabled reads as nobody.
*/
stdioMember?: string;
/**
* GBRA-504: the guest attribution channels a remote call carried (the X-Gbrain-Guest header, request-level
* _meta.guest), set by dispatch from the transport; never from tool arguments. Read only for a write to a guest
* source (guests/admission.ts), and stored nowhere for any other write.
*/
guestChannels?: GuestChannels;
/**
* Set by transports that can widen a session's listed tools (stdio): when
* `request_tools` returns schemas, the named tools join this session's
* tools/list and the client is notified (tools/list_changed).
*/
revealTools?: (names: string[]) => void;
/**
* Subagent runtime context (v0.16+). Set by the subagent tool dispatcher when
* dispatching an op as a tool call from an LLM loop. Used to enforce per-op
* agent policy (e.g. put_page namespace rule).
*
* `viaSubagent` is the FAIL-CLOSED flag: when true, agent-facing policy MUST
* be enforced even if `subagentId` happens to be undefined (a bug in the
* dispatcher must not bypass the guard). `subagentId` is the owning subagent
* job id; `jobId` is the current Minion job id (aggregator or subagent).
*/
jobId?: number;
subagentId?: number;
viaSubagent?: boolean;
/**
* Trusted-workspace allow-list (v0.23 dream cycle). When the cycle's
* synthesize/patterns phases dispatch a subagent, they thread an
* explicit list of slug-prefix globs (e.g. "wiki/personal/reflections/*")
* through this field. put_page enforces it BEFORE the legacy
* `wiki/agents/<id>/...` namespace check.
*
* Local jobs receive these from the trusted submitter. Remote-owned jobs
* receive intersected grant prefixes and auth; prefixes alone grant no trust.
* Every subagent tool call has `remote=true` for auto-link safety,
* so basing trust on `remote` is incoherent (would always reject).
*
* Empty / unset → fall back to the legacy namespace check (existing
* v0.15 behavior; pure addition, no regression).
*/
allowedSlugPrefixes?: string[];
/**
* #5994: the stored authority of a failed write that `gbrain repair
* failed-writes` replays. Set only by that trusted local repair lane; no
* transport, dispatcher or job hydrates it. Admission reuses it as the
* write's authority ceiling (principal, delegation, source incarnation,
* autoLinkTrusted), re-authorized against the live grant, instead of
* deriving local authority from the replay context. The subagent fence
* accepts a missing `subagentId` only with this marker and a non-empty
* allow-list equal to the stored delegated prefixes.
*/
replayAuthority?: WriteAuthority;
/**
* GST-359 D: the attested operation a nested write serves (memory_write saves through remember). Set by the handler,
* never from arguments; the stored authority keeps it, so publication re-checks that operation's attest right.
*/
attestedOp?: string;
/**
* GST-1113: the scope source an attested memory_write named (source_id), allowed by the credential's attest_sources
* (access/attest-sources.ts). Set by the handler, never from arguments; the stored authority keeps it.
*/
attestedSource?: string;
/**
* #4216 — defer chunk embeddings on put_page writes: importFromContent runs
* noEmbed and the standing embed machinery (embed phase / phase-end
* backfill / the stale-embed sweep) picks the chunks up via the
* `embedding IS NULL` partial index. Set ONLY by server-side dispatchers
* (the oneshot runner's programmatic writes); never hydrated from any wire
* payload, so remote callers cannot toggle it. (Flag spelled without dashes
* here on purpose — the flag-registry generator harvests bare dash-dash
* tokens from comments.)
*/
deferEmbeds?: boolean;
/**
* #5232: how long a coordinated write waits for its commit before returning
* `write_pending` with its receipt. Unset keeps the agent default (5 s);
* CLI entry points and the resident owner's CLI lane set it
* (persistence/write-wait.ts).
*/
writeWaitMs?: number;
/**
* Row shape for `search`/`query` results in content[0]. Set by the MCP
* transports: 'full' for gbrain's own thin client (X-Gbrain-Client header)
* and for hosts with `mcp.result_rows: full`, otherwise 'lean'. Unset means
* 'lean' for remote callers; trusted local callers (`remote === false`)
* always get full rows. A per-call `fields: "full"` overrides 'lean'.
* Shape only, never authority: nothing security-relevant reads it.
*/
resultRows?: 'lean' | 'full';
/**
* Large pages (Wave A): the caller identified itself as gbrain's thin client
* (X-Gbrain-Client header). A thin client that names no `body` mode on
* get_page renders compiled_truth as the whole page, so the read is full
* or refused, never a window. Shape only, never authority.
*/
thinClient?: boolean;
/**
* Whether this caller can call `opName` on its surface right now: the MCP
* dispatch predicate (the stdio session's surface after any `request_tools`
* widening, the HTTP client's effective surface and scopes under the
* server ceiling). Set by MCP dispatch only; publish-gated ops read as not
* callable. Unset on local and in-process callers. Shape only, never
* authority: dispatch enforces callability itself.
*/
isCallable?: (opName: string) => boolean;
/**
* Resolved global CLI options (--quiet / --progress-json / --progress-interval).
* CLI callers populate this from `getCliOptions()`. MCP / library callers
* may leave it undefined — consumers default to quiet/no-progress for
* background work.
*/
cliOpts?: { quiet: boolean; progressJson: boolean; progressInterval: number };
/**
* v0.28: per-token allow-list for the holder field on `takes`. Threaded
* by the MCP HTTP/stdio dispatch layer from `access_tokens.permissions.takes_holders`.
*
* When set (i.e., this OperationContext came from an MCP-bound token),
* `takes_list`, `takes_search`, `takes_scorecard`, `takes_calibration`,
* and `query` (when it returns takes) MUST apply `WHERE holder = ANY($takesHoldersAllowList)`.
* This is the server-side filter that backs the v0.28+ visibility model.
*
* v0.30.0: aggregate ops (`takes_scorecard`, `takes_calibration`) require
* the allow-list as a TS-required engine method param (fail-closed by
* compiler). Hidden-holder rows contribute zero to aggregates. The CLI
* callers (local + trusted) leave it undefined.
*
* Default behavior when unset: local CLI callers see all holders. v0.28
* MCP dispatch sets it to `['world']` for tokens with no permissions row
* (default-deny on private hunches).
*/
takesHoldersAllowList?: string[];
/**
* Connected-gbrains brain id (v0.19+ / v0.26 mounts). Identifies which brain
* this op is targeting. 'host' for the default brain configured in
* ~/.gbrain/config.json; otherwise a mount id registered in ~/.gbrain/mounts.json.
*
* `ctx.engine` is the resolved BrainEngine for this id (populated by
* BrainRegistry at dispatch time). `brainId` exists alongside for:
* - audit logging (mount-ops JSONL carries the id)
* - subagent inheritance (child jobs receive the parent's brainId)
* - cross-brain citation prefixes in agent output
*
* Orthogonal to v0.18.0's source_id, which scopes per-repo WITHIN a brain.
* See docs/architecture/brains-and-sources.md for the mental model.
*
* Omitted = 'host' (pre-v0.19 callers + single-brain deployments keep
* working without change).
*/
brainId?: string;
/**
* v0.31 (eD4 / eE2): the in-DB tenancy axis for facts hot memory.
* `sources.id` is TEXT (not INTEGER) — keep this as a string.
*
* Resolved once in the dispatcher from CLI flag (--source) / env
* (GBRAIN_SOURCE) / `.gbrain-source` dotfile / per-token sources scope
* (HTTP). Defaults to 'default' when nothing else applies.
*
* Every facts read/write filter starts with `WHERE source_id = $X`
* so the trust boundary is part of the index path, not a callback.
*
* v0.34 D4 — REQUIRED at the TypeScript level. Mirrors v0.26.9 `remote`
* REQUIRED pattern that closed the HTTP RCE class. Every transport
* (CLI / stdio MCP / HTTP MCP / subagent dispatcher) MUST populate
* this field; `buildOperationContext` auto-fills 'default' for callers
* who don't pass an explicit sourceId, so the type contract is
* satisfied even on single-source brains.
*/
sourceId: string;
/**
* CX2-11 — opaque per-session identity, set from MCP `_meta.session_id`
* (clamped to 256 chars at the dispatch boundary). Cache/telemetry identity
* ONLY — never an auth or trust surface. The hot-memory meta hook keys its
* cache on (sourceId, sessionId, allowlist-hash); before this typed field
* existed every caller collapsed onto the null-session cache key.
*/
sessionId?: string;
/**
* #2561 / #3242 — federated read scope for UNQUALIFIED reads.
*
* Set ONLY by trusted server-side context builders — never from caller
* params — and only when the caller carries no explicit source scope:
* - local CLI (src/cli.ts makeContext) when the source resolved via a
* non-explicit tier (local_path / brain_default / sole_non_default /
* seed_default — NOT --source, NOT GBRAIN_SOURCE, NOT a dotfile);
* - stdio MCP (src/mcp/server.ts) when GBRAIN_SOURCE is unset;
* - HTTP MCP (src/mcp/http-transport.ts) for legacy bearer tokens with
* NO operator-set `permissions.source_id` grant (the historical
* 'default' floor). Tokens WITH an explicit grant never widen.
*
* Contains the resolved source first, then every other
* `config.federated = true` source, so an unqualified read/search spans
* federated sources as docs/guides/multi-source-brains.md promises.
*
* Consumed exclusively by `federatedSearchScope` and the graph-four
* re-route `routeCodeIntelScope` (#4011). Fail-closed remains:
* a grant (`ctx.auth.allowedSources`) or a per-call `source_id` always
* wins, and a context without this field never widens.
*/
localFederatedSourceIds?: string[];
/**
* N2-2 — true when the trusted local CLI (src/cli.ts makeContext) resolved
* `sourceId` from a non-explicit tier (local_path / brain_default /
* sole_non_default / seed_default, or the pre-init 'default' fallback), i.e.
* the operator did not select a source. Lets ops whose data has no source
* axis (find_contradictions' brain-wide stored reports) answer the bare
* command. Ignored unless `remote === false`; a grant always wins.
*/
localSourceImplicit?: boolean;
/**
* #5081 — explicit-read admission for a stdio connection bound by an
* explicit tier (`GBRAIN_SOURCE` or a `.gbrain-source` pin). Set ONLY by
* the stdio transport (src/mcp/server.ts), never from caller params and
* never for an HTTP token. Unlike `localFederatedSourceIds` it never widens
* an unqualified read; `federatedSearchScope` only uses it to admit an
* explicit per-call `source_id` inside `sourceIds`.
*/
explicitReadBinding?: ExplicitReadBinding;
}
/**
* #5081 — the bound source, how it was bound, the sources an explicit
* `source_id` read may name (the bound source first, then every non-archived
* `config.federated === true` source; just the bound source when it opted out
* with `config.federated === false`), and the sources that opted out, which
* only shape the denial hint.
*/
export interface ExplicitReadBinding {
sourceId: string;
via: 'GBRAIN_SOURCE' | '.gbrain-source';
sourceIds: string[];
optedOut: string[];
}
/**
* How an op's response is treated before it reaches any caller. `operations.ts`
* wraps the handler of every `'retrieval'` op once at registration, so the CLI,
* both MCP transports, subagent tools and `gbrain call` all get the same pass:
* `redactRetrievalOutput` (canonical scanner, assignment rule on, uncapped)
* over the whole response, early returns included.
* - `{ retrieval: { localVerbatim } }`: same pass, but the named top-level keys
* are returned unscanned to the trusted local CLI owner (`ctx.remote === false`).
* - `{ exempt }`: returns stored text deliberately raw; the reason is required.
* - `'no_stored_text'`: returns no page, chunk, fact, take or transcript text.
*/
export type OutputRedactionPolicy =
| 'retrieval'
| { retrieval: { localVerbatim: readonly string[] } }
| { exempt: string }
| 'no_stored_text';
export interface Operation {
name: string;
description: string;
params: Record<string, ParamDef>;
/**
* GST-1493: one sentence with a valid call as JSON, appended to the suggestion when dispatch refuses an unknown
* parameter, so a client that never read the schema gets the whole required shape, not only the nearest name.
*/
callShape?: string;
handler: (ctx: OperationContext, params: Record<string, unknown>) => Promise<unknown>;
outputRedaction: OutputRedactionPolicy;
mutating?: boolean;
/**
* What model work this write may do and when (`src/core/ops/write-inference.ts`).
* Unset resolves through OP_WRITE_INFERENCE, then to `'none'`.
*/
writeInference?: WriteInference;
/**
* Agent contract v1 (A2): repeating the call with the same arguments (and,
* for journaled writes, the same request identity) has the same effect as
* calling it once. Drives `idempotentHint` and whether an unknown-outcome
* failure may say `retryable: true`.
*/
idempotent?: boolean;
/**
* Capability scope required to invoke this op over an authenticated
* transport. v0.28 added `sources_admin` (manage federated sources) and
* `users_admin` (reserved). The hierarchy lives in src/core/scope.ts —
* `admin` implies all, `write` implies `read`, the two `*_admin` scopes
* are siblings (different axes; neither implies the other). `agent` is
* also a sibling NOT implied by admin (v0.38 D13): admin tokens must be
* explicitly re-registered with bindings to touch the agent lane.
*
* Local CLI callers (ctx.remote === false) bypass scope enforcement
* because the trust boundary there is the OS, not OAuth scopes.
*/
scope?: 'read' | 'write' | 'admin' | 'sources_admin' | 'users_admin' | 'agent';
requiredScopes?: readonly string[];
localOnly?: boolean;
/**
* Agent contract v1 (F5): the handler refuses every agent-facing caller,
* stdio included; only the trusted local CLI runs it. `isCallable` never
* lists it on MCP, and a call returns `cli_only` whose fix is this exact
* command (`<name>` tokens are inputs the agent fills from its call).
*/
cliOnly?: { argv: readonly string[] };
/**
* WP1 honest catalog: the op is callable by remote callers only when this
* config gate resolves true (dual-plane, DB > file > absent=false). Network
* transports hide the op from tools/list while the gate is off — a listed
* tool that always denies reads as broken, not private. The in-handler
* gate (assertPublishEnabled / the advisor inline check) stays as the
* fail-closed call-time backstop; stdio (local pipe) bypasses publish
* gates entirely. Resolution lives in src/mcp/publish-gates.ts.
*/
publishGateKey?: 'mcp.publish_skills' | 'mcp.publish_advisor' | 'mcp.publish_memory_settings' | 'mcp.publish_wakeshift';
/**
* MEMORY_VERBS v1: marks the seven frozen protocol verbs (recall, remember,
* entity, synthesize, forget, context_pack, delta). `gbrain serve --surface
* verbs` exposes EXACTLY the ops with `verb: true`; 'starter' (the ~20-op
* daily-driver tier) sits between verbs and `full` (default), which exposes
* everything.
*/
verb?: boolean;
/**
* WP4 (amendment 22) — coarse grouping label consumed by the
* `request_tools` catalog and the generated tool-catalog doc. Area NAMES
* ARE NON-CONTRACTUAL: they exist so an agent can scan ~20 groups instead
* of ~100 flat names; renaming/regrouping is never a breaking change.
* Required (by the CI walker in test/mcp-tool-defs.test.ts) on every
* non-localOnly op; populated centrally via OP_AREAS in
* src/core/operation-load.ts.
*/
area?: string;
/**
* WP4 (FOV-4) — marks a discovery meta-op callable by the `agent` scope
* IN ADDITION to its declared scope. `agent` deliberately implies only
* itself (v0.38 D13), which would strand agent-only tokens with zero
* discovery; the MCP scope checks (serve-http tools/list + tools/call)
* add a one-line carve-out for ops with this flag. Currently only
* `request_tools`.
*/
agentCallable?: true;
/**
* MCP ToolAnnotations passthrough (SDK 1.29+). Emitted by buildToolDefs
* ONLY when set — existing tools keep byte-identical definitions.
*/
annotations?: {
title?: string;
readOnlyHint?: boolean;
destructiveHint?: boolean;
idempotentHint?: boolean;
};
cliHints?: {
name?: string;
/**
* Alternate CLI command names that dispatch to this same op (v114 / #1941).
* e.g. `link-add` aliasing `link`. Registered in `cli.ts`'s `cliAliases`
* map; collisions with primary names or CLI_ONLY commands throw at startup.
*/
aliases?: string[];
positional?: string[];
stdin?: string;
hidden?: boolean;
};
}
/**
* Everything about an operation except its handler: the data tools/list,
* surface filtering, publish gates and CLI arg parsing read. Checked in as
* src/core/operation-manifest.generated.ts so `gbrain serve` and the CLI
* dispatcher can answer without loading every handler module.
*/
export type OperationMeta = Omit<Operation, 'handler'>;
/**
* An op that declares its own `source` param (timeline-add, ontology-add,
* takes add/update/supersede, raw data) takes `--source` as that param, e.g.
* provenance. Every CLI route (direct, delegated to a resident serve, thin
* client) then leaves it out of source scoping and passes it to the handler.
*/
export function opOwnsSource(op: Pick<Operation, 'params'>): boolean {
return 'source' in op.params;
}