Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import type { BrainEngine } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { operations } from '../operations.ts';
import { opError, OperationError, type AuthInfo } from '../ops/contract.ts';
import { hasScope, operationScopesAllowed } from '../scope.ts';
import { resolveSourceId } from '../source-resolver.ts';
import { dispatchToolCall } from '../../mcp/dispatch.ts';
import { registerLocalWriter, withVerifiedLocalRegistration } from './identity.ts';
import { startPersistenceConsumer, assertPersistenceAccepting } from './service.ts';
import { isWriteErrorCode, isWriteReceipt } from './types.ts';
import { LOCAL_CLI_OWNER_OPERATIONS, PERSISTENCE_ROOM_MARKED_KEY, restoreRecoveryContract, type PersistenceIpcProvider } from './ipc.ts';
import { currentCallerAccess } from '../search/private-visibility.ts';
import { runPersistenceAdministration } from './administration.ts';
import { boundedWriteWaitMs } from './write-wait.ts';
export { residentPersistenceConfig } from './local-client.ts';
import { startProjectionStatusCache } from '../page-state/projection-status.ts';
import { trustedCliRequired } from '../ops/op-fix.ts';
import type { Action } from '../agent-output.ts';
const localWritersFix: Action = { argv: ['gbrain', 'auth', 'local-writer', 'list', '--json'], consent: [], actor: 'agent',
why: 'Shows this brain\'s local writer registrations with their grants, read-only.', requires_exclusive: false };
/**
* localOnly operations the verified local CLI may run through the resident
* owner: dispatched with the `stdio` locality marker so the localOnly
* backstop admits them; remote principals never get it.
*/
const LOCAL_CLI_LOCAL_ONLY_OPS = new Set(['takes_remove', 'takes_rebuild']);
/** Resident lifecycle owns the consumer; each connection proves its own durable registration. */
export async function createPersistenceIpcProvider(engine: BrainEngine, config: GBrainConfig): Promise<PersistenceIpcProvider> {
for (const lane of ['cli', 'stdio'] as const) {
try { await registerLocalWriter(engine, lane); }
catch (error) {
// Revocation persists across restart. Other principals can still use this owner.
if (!(error instanceof OperationError && error.code === 'permission_denied')) throw error;
}
}
const [brain] = await engine.executeRaw<{ brain_id: string }>('SELECT brain_id FROM persistence_brain WHERE singleton=1');
startPersistenceConsumer(engine, config);
const projectionStatus = startProjectionStatusCache(engine);
return { brainId: brain.brain_id, projectionStatus: () => projectionStatus.read(), dispatch: request => withVerifiedLocalRegistration(engine, request.registration, async verified => {
assertPersistenceAccepting(engine);
if (request.brain_id !== brain.brain_id) {
throw opError('permission_denied', 'This registration belongs to a different brain.',
'The CLI sent a writer registration for another brain to this brain\'s owner. Select the intended brain with --brain; registering this CLI on this brain is a credentials step the user approves.',
{ fix: localWritersFix });
}
const operation = operations.find(op => op.name === request.operation);
const localSkillAdministration = !verified.remote && verified.principal.kind === 'local_cli'
&& (['get_skill_policy', 'set_skill_policy', 'get_skill_retention', 'prune_skill_revisions', 'retain_skill_revision', 'import_skill_proposal'].includes(request.operation)
|| LOCAL_CLI_OWNER_OPERATIONS.has(request.operation));
if (!operation || (!localSkillAdministration && !hasScope(verified.grant.scopes, operation.scope ?? 'read'))
|| (verified.remote && !operationScopesAllowed(verified.grant.scopes, operation))
|| (verified.grant.operations !== null && !verified.grant.operations.includes(operation.name))) {
throw opError('permission_denied', 'The local writer grant excludes this operation.',
`This CLI's writer grant does not cover ${request.operation}. Review the grant; widening it with gbrain auth local-writer register --replace is a credentials change the user approves.`,
{ fix: localWritersFix });
}
const sourceId = await resolveSourceId(engine, request.routing.source, request.routing.cwd, { skipLocalSignals: true });
const unrestricted = verified.grant.sourceIds.includes('*');
const sourceAllowed = (source: unknown) => typeof source === 'string' && (unrestricted || verified.grant.sourceIds.includes(source));
if (!sourceAllowed(sourceId) || (request.params.source_id !== undefined && !sourceAllowed(request.params.source_id))) {
throw opError('permission_denied', 'The local writer grant excludes this source.',
`This CLI's writer grant does not cover source ${String(request.params.source_id ?? sourceId)}. Use a source the grant lists; widening it is a credentials change the user approves.`,
{ fix: localWritersFix });
}
// AuthInfo carries server-constructed read/fence ceilings; durable identity
// remains in the verifier's async context, never a fabricated OAuth identity.
const auth: AuthInfo = { token: '', clientId: verified.principal.id, scopes: [...verified.grant.scopes],
sourceId, allowedOperations: verified.grant.operations, boundSlugPrefixes: verified.grant.slugPrefixes ?? undefined,
allowedSources: unrestricted ? undefined : verified.grant.sourceIds };
const params = !unrestricted && request.operation === 'get_page' && request.params.source_id === undefined
? { ...request.params, source_id: sourceId } : request.params;
// `gbrain transcripts recent` through the live owner: the verified local CLI reads the host's transcript
// files directly, as it does without a serve (localOnly ops never dispatch off the stdio pipe).
if (request.operation === 'get_recent_transcripts') {
if (verified.remote || verified.principal.kind !== 'local_cli') throw trustedCliRequired('Raw transcripts are read only by this host\'s trusted CLI.');
const p = request.params;
return (await import('../transcripts.ts')).listRecentTranscripts(engine, { days: typeof p.days === 'number' ? p.days : undefined,
summary: typeof p.summary === 'boolean' ? p.summary : undefined, limit: typeof p.limit === 'number' ? p.limit : undefined });
}
const localCliLocalOnly = !verified.remote && verified.principal.kind === 'local_cli' && LOCAL_CLI_LOCAL_ONLY_OPS.has(request.operation);
const writeWaitMs = boundedWriteWaitMs(request.write_wait_ms);
const result = await dispatchToolCall(engine, request.operation, params, {
// #6696 (A5): a verified local registration is the user's CLI or agent, as on the in-process entry points.
admissionOrigin: 'interactive', pendingAsError: true,
config, remote: verified.remote, transport: verified.remote || localSkillAdministration || localCliLocalOnly ? 'stdio' : undefined, sourceId, auth,
...(writeWaitMs !== undefined ? { writeWaitMs } : {}),
...(unrestricted ? {} : { localFederatedSourceIds: verified.grant.sourceIds }),
...(request.routing.source === null && !verified.remote ? { localSourceImplicit: true } : {}),
});
const body = JSON.parse(result.content[0].text) as Record<string, unknown>;
// GBRA-498: the trusted local CLI's --room is marked here, where the brain is; any other lane's answer goes back
// unmarked and the CLI marks every item unknown.
const answer = async (): Promise<unknown> => {
if (request.room === undefined || verified.remote || verified.principal.kind !== 'local_cli') return body;
const { assessRoom, readRoomDeclaration } = await import('../access/room.ts');
const room = await assessRoom(engine, { op: request.operation, result: body, sourceId,
declaration: readRoomDeclaration({ requestMeta: { room: request.room } }, undefined).declaration!,
caller: { access: currentCallerAccess(), transport: 'cli', local: true } });
return { [PERSISTENCE_ROOM_MARKED_KEY]: { result: room.result, meta: room.meta, notices: room.stamped } };
};
if (!result.isError) return answer();
// GST-1387: a remember batch with a failed item keeps every item's receipt; the CLI exits 1 on its status.
if (Array.isArray(body.items) && body.status === 'error') return answer();
const error = new OperationError(typeof body.error === 'string' ? body.error : 'unavailable',
typeof body.message === 'string' ? body.message : 'The local operation could not complete.',
typeof body.suggestion === 'string' ? body.suggestion : undefined);
restoreRecoveryContract(error, body);
if (isWriteReceipt(body.write_request)) error.writeRequest = body.write_request;
if (isWriteErrorCode(body.write_error)) error.writeError = body.write_error;
if (body.protocol_version === 1) error.protocolVersion = 1;
throw error;
}), administer: request => withVerifiedLocalRegistration(engine, request.registration, async verified => {
assertPersistenceAccepting(engine);
if (request.brain_id !== brain.brain_id || verified.remote || verified.principal.kind !== 'local_cli') {
throw trustedCliRequired('Local administration requires this brain’s current trusted CLI registration.');
}
return runPersistenceAdministration(engine, request.operation, request.params, config);
}) };
}