Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* whoami + sources-management operation cluster — pure move from
* operations.ts (v0.46.x tranche 3). Op consts stay module-private;
* `sourcesOperations` below lists them in EXACTLY the order they appear in
* the canonical `operations` array in ../operations.ts. Never import from
* '../operations.ts' here (cycle).
*/
import type { Operation, OperationContext } from './contract.ts';
import { authTransport, opError } from './contract.ts';
import { hostFix, hostOnlyError, paramUse } from './op-fix.ts';
import { isValidSourceId } from '../source-id.ts';
import { assertSourceInCallerScope, assertSourceInCallerWriteScope, readPolicyOpts, sourceScopeOpts } from './context.ts';
import { resolveAuthCapabilities, resolveGrantDiagnosis } from '../harness/capabilities.ts';
// --- v0.28: whoami + sources management ---
/** A source id from params, validated for argv; an unsafe id is left out rather than interpolated. */
function sourceIdArg(id: unknown): string[] {
return isValidSourceId(id) ? [id] : [];
}
/** B6: managed source lifecycle runs only on the verified owner CLI; the refusal names the exact host command. */
function managedLifecycleRefusal(ctx: OperationContext, args: string[]) {
return hostOnlyError(ctx, 'writer_coordinator_required',
'Managed source lifecycle requires the verified owner CLI. An ordinary MCP grant does not confer owner administration authority.',
['gbrain', ...args],
'With managed persistence on, adding or removing a source changes the brain\'s writer topology, which only its owner CLI may do.');
}
/** GBRA-498: what this server supports, so a harness checks once per connection (room: room-aware results, access/room.ts). */
const WHOAMI_FEATURES = { room: true } as const;
const whoami: Operation = {
name: 'whoami',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Your identity: transport, scopes and, over OAuth, client, source_id and federated_read.',
params: {},
scope: 'read',
handler: async (ctx) => {
// Trust boundary: ctx.remote === false is the trusted local CLI surface.
// Returning OAuth-shaped scopes here would resurrect the v0.26.9 footgun
// where code conditionally trusted on `scopes.includes('admin')` instead
// of `ctx.remote === false`. Empty scopes array forces clients to
// special-case `transport: 'local'` explicitly.
// F2: config-plane readiness (sync, in-memory config) rides every shape.
const { configReadiness, readinessHttpView } = await import('../readiness.ts');
const readiness = (transport: 'cli' | 'stdio' | 'http') => {
const entries = configReadiness(ctx.config, { transport }).entries;
return transport === 'http' ? readinessHttpView(entries) : entries;
};
const { accessView, appliedAccessSummary, credentialAccessView, stdioAccessView } = await import('../access/caller.ts');
// GBRA-231: the view this call is answered under (the shared-agent audience when the harness asserted one), so a
// model can check it when its harness does not forward _meta.access.
// GST-2490: and, while the owner opt-in is on, that the owner reads the pages kept to this caller; GBRA-108: and,
// while access.members_read_lineage is on, that members read the derived pages of pages listed to them.
const withApplied = async <T extends object>(view: T) => ({ ...view, applied: await appliedAccessSummary(ctx.engine, ctx.auth, [ctx.sourceId, ...(ctx.localFederatedSourceIds ?? [])]),
...await (await import('../access/owner.ts')).ownerReadsRestrictedNotice(ctx.engine),
...await (await import('../access/lineage.ts')).membersReadLineageNotice(ctx.engine),
// GST-363: and, remotely, what the requester-scope gate does with this connection's reads.
requester_scope: await (await import('../access/requester-scope.ts')).requesterScopeView(ctx.engine, (await import('../search/private-visibility.ts')).currentCallerAccess(), ctx.auth, ctx.transport) });
if (ctx.remote === false) {
// GBRA-218: a local --as <member> preview reports the member it reads as; the plain local CLI reads every page.
const access = ctx.applyRemoteReadPolicy && ctx.accessIdentity?.length ? accessView(ctx.accessIdentity, 'as')
: accessView([], 'none', null, 'The local CLI reads every page; pass --as <member> to preview what a member can read.');
return { transport: 'local', scopes: [], features: WHOAMI_FEATURES, access, readiness: readiness('cli') };
}
// #1061: stdio MCP is remote/untrusted by design but has no per-token
// auth (local pipe) — a known transport, not a bug. Report it instead of
// throwing. Scopes are the verified stdio registration's grant (the same
// scopes gbrain://capabilities reports and dispatch enforces); [] without one.
if (!ctx.auth && ctx.transport === 'stdio') {
const { readLocalWriter, verifyLocalWriter } = await import('../persistence/identity.ts');
let scopes: readonly string[] = [];
try {
const verified = await verifyLocalWriter(ctx.engine, await readLocalWriter(ctx.engine, 'stdio'));
if (verified.remote) scopes = verified.grant.scopes;
} catch { /* no registration: no scopes */ }
const session = ctx.stdioSurface;
return { transport: 'stdio', scopes, features: WHOAMI_FEATURES, ...(session ? { surface: session.surface, surface_source: session.source } : {}), access: await withApplied(await stdioAccessView(ctx.engine, ctx.stdioMember)), readiness: readiness('stdio') };
}
if (!ctx.auth) {
throw opError(
'unknown_transport',
'whoami called over a remote transport that did not thread ctx.auth. ' +
'This is a transport bug — every remote call site must populate ctx.auth ' +
'or set ctx.remote === false.',
'This is a gbrain server bug, not a caller mistake: tell the user, and have `gbrain doctor --json` run on the brain host.',
);
}
// Legacy access_tokens reuse `name` as both clientId and clientName, so the
// transport comes from the verifier-set principal (prefix only as fallback).
if (authTransport(ctx.auth) === 'oauth') {
return {
transport: 'oauth',
features: WHOAMI_FEATURES,
client_id: ctx.auth.clientId,
client_name: ctx.auth.clientName ?? ctx.auth.clientId,
...await resolveAuthCapabilities(ctx.auth, ctx.engine, ctx.config, { surfaceCeiling: ctx.surfaceCeiling }),
access: await withApplied(await credentialAccessView(ctx.engine, ctx.auth)),
};
}
return {
transport: 'legacy',
features: WHOAMI_FEATURES,
token_name: ctx.auth.clientName ?? ctx.auth.clientId,
scopes: ctx.auth.scopes,
expires_at: null,
access: await withApplied(await credentialAccessView(ctx.engine, ctx.auth)),
grant_diagnosis: await resolveGrantDiagnosis(ctx.auth, ctx.engine, ctx.config, { surfaceCeiling: ctx.surfaceCeiling }),
readiness: readiness('http'),
};
},
cliHints: { name: 'whoami' },
};
const sources_add: Operation = {
name: 'sources_add',
idempotent: false,
outputRedaction: 'no_stored_text',
description:
'Register a new source. Supports either path (a local directory) ' +
'or url (a remote clone: parses the URL through the ' +
'SSRF gate, clones into $GBRAIN_HOME/clones/<id>/ via temp-dir + rename ' +
'atomicity, and stores remote_url in sources.config). Pre-flight collision ' +
'check on id; rollback on either-side failure.',
params: {
id: {
type: 'string',
required: true,
description: 'Source id ([a-z0-9-]{1,32}). Immutable citation key.',
},
name: { type: 'string', description: 'Display name (defaults to id).' },
path: { type: 'string', description: 'Local path. Mutually optional with url.' },
url: {
type: 'string',
description:
'HTTPS git URL. Cloned into $GBRAIN_HOME/clones/<id>/. SSRF-guarded.',
},
federated: {
type: 'boolean',
description: 'true → cross-source default search. false → isolated.',
},
clone_dir: {
type: 'string',
description:
'Override clone destination (only valid with url). Default: $GBRAIN_HOME/clones/<id>/.',
},
},
mutating: true,
scope: 'sources_admin',
handler: async (ctx, p) => {
const { addSource, SourceOpError } = await import('../sources-ops.ts');
if(ctx.remote!==false&&await (await import('../persistence/ownership.ts')).managedPersistenceEnabled(ctx.engine))
throw managedLifecycleRefusal(ctx, ['sources', 'add', ...sourceIdArg(p.id), ...(typeof p.url === 'string' && /^https:\/\/\S+$/.test(p.url) ? ['--url', p.url] : [])]);
// v0.28.1 codex finding (CRITICAL + HIGH): a `sources_admin` token over
// HTTP MCP must not be able to plant content at arbitrary host paths.
//
// - `path` lets a remote caller register `/etc/` (or any host dir) as a
// "source"; later `gbrain sync --all` walks every sources.local_path,
// which exfiltrates host content into the brain.
// - `clone_dir` lets a remote caller name the destination directly;
// addSource's renameSync places the cloned tree there with no
// confinement, AND validateRepoState's degraded-state recovery later
// does rm -rf on src.local_path, so the same primitive doubles as
// arbitrary-delete.
//
// Both fields are CLI-only (the operator runs `gbrain sources add --path
// /home/me/notes`). For HTTP MCP, ignore overrides — clone_dir defaults
// to $GBRAIN_HOME/clones/<id>/ and path is rejected. Local CLI callers
// (ctx.remote === false, per F7b fail-closed contract) keep the override.
const isLocal = ctx.remote === false;
const remotePath = isLocal ? (p.path as string | undefined) ?? null : null;
const remoteCloneDir = isLocal ? (p.clone_dir as string | undefined) : undefined;
if (!isLocal && p.path !== undefined) {
throw opError(
'invalid_params',
'sources_add: path is not honored over MCP (security confinement). ' +
'Register with `url` instead, or run `gbrain sources add <id> --path <dir>` on the host CLI.',
`Pass ${paramUse(ctx, 'url', 'https://github.com/owner/repo')} to register a remote Git source, or have the host run the command in fix to register this local directory.`,
{ fix: hostFix(ctx, ['gbrain', 'sources', 'add', ...sourceIdArg(p.id), '--path', String(p.path)],
'Local directories can only be registered by the trusted CLI on the brain host (MCP callers cannot plant host paths).') },
);
}
const row = await addSource(ctx.engine, {
id: p.id as string,
name: p.name as string | undefined,
localPath: remotePath,
remoteUrl: p.url as string | undefined,
addedByRemoteCaller: !isLocal,
federated:
p.federated === undefined ? null : (p.federated as boolean),
cloneDir: remoteCloneDir,
}).catch((err: unknown) => {
// git's own error names the far end and how it answered; a remote caller gets a fixed message, the host log keeps it.
if (isLocal || !(err instanceof SourceOpError) || err.code !== 'clone_failed') throw err;
console.error(`[gbrain] sources_add ${String(p.id)}: ${err.message}`);
throw new SourceOpError('clone_failed', 'git clone failed for this URL. The brain host\'s log has the reason.', err);
});
const { redactSourceConfig } = await import('../source-config-redact.ts');
const { parseSourceConfig } = await import('../sources-load.ts');
return { ...row, config: redactSourceConfig(parseSourceConfig(row.config)) };
},
cliHints: { name: 'sources_add', hidden: true },
};
const sources_list: Operation = {
name: 'sources_list',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description:
'List registered sources with page counts and remote_url. remote_url lets ' +
'a remote MCP caller confirm a source is ' +
'managed by clone+pull rather than user-supplied path. Results are ' +
"confined to the caller's resolved source scope (federated read grant > " +
'bound source) and carry no marker when rows were withheld, so a ' +
'listing may be incomplete. Only the trusted local CLI (`gbrain sources ' +
'list`) sees the full registry.',
params: {
include_archived: { type: 'boolean', description: 'Include soft-deleted sources.' },
},
scope: 'read',
handler: async (ctx, p) => {
const { listSources } = await import('../sources-ops.ts');
// #4433: row-filter the listing to the caller's source scope — a client
// whose scope excludes a source must not learn that source's id, name,
// or page_count. Wave-L posture (maintainer decision, supersedes the
// wave-g "scalar callers keep the full listing" carve-out): EVERY
// untrusted caller (anything not strictly remote === false) is confined
// through the canonical sourceScopeOpts ladder, matching the rest of
// the read-op surface — federated grant > scalar bound source >
// fail-closed '__all__' (the sentinel passes through as a literal that
// matches no real source id, so it yields an empty listing rather than
// the whole registry). Trusted local CLI keeps the full operator view.
const scope = ctx.remote === false ? {} : sourceScopeOpts(ctx);
const allowedSourceIds =
scope.sourceIds ?? (scope.sourceId !== undefined ? [scope.sourceId] : undefined);
return {
sources: await listSources(ctx.engine, {
includeArchived: (p.include_archived as boolean) === true,
...(allowedSourceIds !== undefined ? { allowedSourceIds } : {}),
}),
};
},
cliHints: { name: 'sources_list', hidden: true },
};
const sources_remove: Operation = {
name: 'sources_remove',
idempotent: false,
outputRedaction: 'no_stored_text',
description:
'Hard-remove a source (cascades pages/chunks/embeddings). Refuses to ' +
'delete the auto-managed clone dir unless its resolved path is confined ' +
'under $GBRAIN_HOME/clones/ (realpath+lstat — symlink-safe). For most ' +
'workflows prefer the soft-delete path (`gbrain sources archive`). ' +
"Confined to the caller's WRITE authority, not its read scope: an untrusted " +
'caller may remove only its own write source (a federated read grant naming ' +
'a source does not make it removable); any other id answers not_found, ' +
'indistinguishable from a nonexistent source. Only the trusted local CLI ' +
'(`gbrain sources remove`) can remove any source.',
params: {
id: { type: 'string', required: true, description: "Source id to remove, as listed by sources_list (e.g. 'wiki'). A source id, not a page slug." },
confirm_destructive: {
type: 'boolean',
description:
'Required when the source has data (pages, chunks). Without it the op refuses.',
},
dry_run: { type: 'boolean', description: 'Preview impact without side effects.' },
keep_storage: {
type: 'boolean',
description: 'Skip clone-dir cleanup even when the source is auto-managed.',
},
},
mutating: true,
scope: 'sources_admin',
handler: async (ctx, p) => {
// Source isolation on the DESTRUCTIVE path keys on WRITE authority (O4-1;
// supersedes the #4433 wave-L read-ladder check that let a federated read
// grant hard-delete a sibling source): a `sources_admin` token may remove
// only its own write source; out-of-authority ids answer not_found
// (anti-enumeration), an unbound client keeps full authority, trusted
// local CLI passes. sources_status keeps the READ helper.
assertSourceInCallerWriteScope(ctx, p.id as string);
const { removeSource } = await import('../sources-ops.ts');
if(ctx.remote!==false&&await (await import('../persistence/ownership.ts')).managedPersistenceEnabled(ctx.engine))
throw managedLifecycleRefusal(ctx, ['sources', 'remove', ...sourceIdArg(p.id), '--dry-run']);
return removeSource(ctx.engine, {
id: p.id as string,
confirmDestructive: (p.confirm_destructive as boolean) === true,
dryRun: (p.dry_run as boolean) === true || ctx.dryRun,
keepStorage: (p.keep_storage as boolean) === true,
});
},
cliHints: { name: 'sources_remove', hidden: true },
};
const sources_status: Operation = {
name: 'sources_status',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description:
'Per-source diagnostic. Returns clone_state ("healthy" | "missing" | ' +
'"not-a-dir" | "no-git" | "url-drift" | "corrupted" | "not-applicable") ' +
'so a remote MCP caller can diagnose whether the on-disk clone is ' +
"syncable without SSH access to the brain host. Confined to the caller's " +
'resolved source scope; an out-of-scope id answers not_found, ' +
'indistinguishable from a nonexistent source.',
params: {
id: { type: 'string', required: true, description: "Source id to diagnose, as listed by sources_list (e.g. 'wiki'). A source id, not a page slug." },
},
scope: 'read',
handler: async (ctx, p) => {
// Source isolation (#4433 wave-L posture, the maintainer decision that
// superseded the wave-g "scalar callers keep the full listing"
// carve-out), via the helper shared with sources_remove: out-of-scope ids
// answer not_found (matching get_agent_job's shape), trusted local passes.
assertSourceInCallerScope(ctx, p.id as string);
const { getSourceStatus } = await import('../sources-ops.ts');
const status = await getSourceStatus(ctx.engine, p.id as string);
const { readCompanyBrainSourceStatus } = await import('../company-brain/status.ts');
const ingestion = await readCompanyBrainSourceStatus(ctx.engine, p.id as string);
const { readAppliedWatermark } = await import('../persistence/applied-watermark.ts');
const watermark = await readAppliedWatermark(ctx.engine, p.id as string, { remote: ctx.remote !== false }).catch(() => null);
return { ...status, ...(ingestion ? { ingestion } : {}), ...(watermark ? { watermark } : {}) };
},
cliHints: { name: 'sources_status', hidden: true },
};
const sources_inspect: Operation = {
name: 'sources_inspect',
idempotent: true,
outputRedaction: 'no_stored_text',
description: 'Inspect committed company Markdown on the trusted local host without importing, registering a source, changing access, or invoking providers.',
params: {
path: { type: 'string', required: true, description: 'Local committed Git repository directory.' },
profile: { type: 'string', description: 'Optional explicit company-brain profile; omission detects without activating.' },
include: { type: 'array', items: { type: 'string' }, description: 'Repository-relative include globs.' },
exclude: { type: 'array', items: { type: 'string' }, description: 'Repository-relative exclude globs.' },
},
scope: 'read',
localOnly: true, cliOnly: { argv: ['gbrain', 'sources', 'inspect', '<path>'] },
mutating: false,
handler: async (ctx, params) => {
if (ctx.remote !== false) {
throw hostOnlyError(ctx, 'permission_denied', 'Repository inspection requires the trusted local CLI.',
['gbrain', 'sources', 'inspect', String(params.path), '--json'],
'Inspection reads a local Git checkout, which only the trusted CLI on that machine may do.');
}
const { inspectCompanyBrain } = await import('../company-brain/inspection.ts');
return inspectCompanyBrain({ path: params.path as string,
profile: params.profile as 'company-brain' | undefined,
include: params.include as string[] | undefined, exclude: params.exclude as string[] | undefined });
},
cliHints: { name: 'sources_inspect', hidden: true },
};
const sources_resolve_path: Operation = {
name: 'sources_resolve_path',
mutating: false,
idempotent: true,
outputRedaction: 'no_stored_text',
description:
'Read-only: what gbrain did with each file path of a source, by its own rules. Per path: the slug sync gives it, whether ' +
'sync skips it (metafile, excluded, pruned) and why, its sync hold, its page with chunk and embedding counts, whether ' +
'search finds it now, and the command that moves it on. A deleted path is checked by the page that records it as its ' +
'origin, never by slug. Use it in landing checks instead of re-implementing slugging. Confined to the caller\'s source scope.',
params: {
id: { type: 'string', required: true, description: "Source id, as listed by sources_list (e.g. 'default')." },
paths: { type: 'array', items: { type: 'string' }, required: true, description: 'File paths relative to the source root (or to the Git top level), at most 200, e.g. the paths a commit changed.' },
},
scope: 'read',
handler: async (ctx, p) => {
assertSourceInCallerScope(ctx, p.id as string);
const { resolveSourcePaths } = await import('../persistence/resolve-paths.ts');
return resolveSourcePaths(ctx.engine, p.id as string, (p.paths as unknown[] ?? []).map(String), await readPolicyOpts(ctx, { sourceId: p.id as string }));
},
cliHints: { name: 'sources_resolve_path', hidden: true },
};
export const sourcesOperations: Operation[] = [
whoami, sources_add, sources_list, sources_remove, sources_status, sources_inspect, sources_resolve_path,
];