Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
// Serial: captures CLI stdout/fetch and resets the process-wide exit verdict.
import { afterEach, expect, spyOn, test } from 'bun:test';
import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { runMcpAdmin } from '../src/commands/mcp-admin.ts';
import { mcpNeedsEngine, runMcp } from '../src/commands/mcp.ts';
import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';
import { validateCredentials } from '../src/core/harness/credentials.ts';
import { withEnv } from './helpers/with-env.ts';
const owner = 'fixture-owner-credential-'.repeat(2);
const base = 'https://brain.example.com';
const clientId = 'gbrain_cl_admin_fixture';
const secret = 'gbrain_cs_private_fixture';
const session = 'e'.repeat(64);
const temporaries: string[] = [];
const newDirectory = () => { const directory = mkdtempSync(join(tmpdir(), 'gbrain-admin-cli-')); temporaries.push(directory); return directory; };
const login = () => Response.json({ status: 'authenticated' }, { headers: { 'Set-Cookie': `gbrain_admin=${session}; HttpOnly` } });
const setup = (confidential = false) => ({
kind: 'oauth-client-setup', version: 1, flow: 'authorization-code', mcp_url: `${base}/mcp`, issuer_url: base,
scopes: ['read'], harness: 'generic', client: { client_id: clientId, client_name: 'fixture-example',
redirect_uris: ['https://client.example.com/callback'], grant_types: ['authorization_code', 'refresh_token'],
token_endpoint_auth_method: confidential ? 'client_secret_post' : 'none', ...(confidential ? { client_secret: secret } : {}) }, instructions: ['Connect in the native client.'],
});
afterEach(() => {
_resetCliExitVerdictForTests();
process.exitCode = 0;
for (const directory of temporaries.splice(0)) rmSync(directory, { recursive: true, force: true });
});
async function capture(args: string[], handler: (url: string, init: RequestInit) => Promise<Response> | Response) {
const output: string[] = [];
const requests: Array<{ url: string; init: RequestInit }> = [];
const log = spyOn(console, 'log').mockImplementation((...values: unknown[]) => { output.push(values.map(String).join(' ')); });
try {
await runMcpAdmin([...args, '--url', base, '--json'], { bootstrapToken: owner, fetchImpl: (async (url, init) => {
requests.push({ url: String(url), init: init! });
return String(url).endsWith('/admin/login') ? login() : handler(String(url), init!);
}) as typeof fetch });
return { result: JSON.parse(output.at(-1)!), output: output.join('\n'), requests, exitCode: currentExitCode() };
} finally { log.mockRestore(); }
}
test('every admin command routes without opening an engine; env owner credential also routes grant remotely', async () => {
for (const command of ['clients', 'client', 'login-link', 'register', 'setup', 'revoke', 'delete', 'invalidate-tokens']) {
expect(mcpNeedsEngine(['admin', command], undefined)).toBe(false);
}
await withEnv({ GBRAIN_ADMIN_BOOTSTRAP_TOKEN: undefined }, async () => {
expect(mcpNeedsEngine(['grant', 'fixture'])).toBe(true);
expect(mcpNeedsEngine(['grant', 'fixture', '--admin-token-file', '/private/token'])).toBe(false);
});
await withEnv({ GBRAIN_ADMIN_BOOTSTRAP_TOKEN: owner }, async () => {
expect(mcpNeedsEngine(['grant', 'fixture'])).toBe(false);
const requests: string[] = [];
const fetchMock = spyOn(globalThis, 'fetch').mockImplementation((async url => {
requests.push(String(url));
return String(url).endsWith('/admin/login') ? login() : Response.json({
dry_run: true, grant: { clientId: 'preview', budgetUsdPerDay: null }, before: null, credentials: null, credential_action: 'none',
});
}) as typeof fetch);
const messages: string[] = [];
const logger = spyOn(console, 'log').mockImplementation(message => { messages.push(String(message)); });
try {
await runMcp(['grant', 'fixture', '--url', `${base}/mcp`, '--dry-run', '--json']);
expect(currentExitCode()).toBe(0);
expect(JSON.parse(messages[0]).status).toBe('preview');
expect(requests).toEqual([`${base}/admin/login`, `${base}/admin/api/grants`]);
expect(messages.join('')).not.toContain(owner);
} finally { fetchMock.mockRestore(); logger.mockRestore(); }
});
});
test('native public registration sends all redirect URIs and creates no machine flow', async () => {
const result = await capture(['register', 'fixture-example', '--redirect-uri', 'https://client.example.com/callback', '--redirect-uri', 'fixture-app://oauth'], (_url, init) => {
const body = JSON.parse(String(init.body));
expect(body).toMatchObject({ grantTypes: ['authorization_code', 'refresh_token'], tokenEndpointAuthMethod: 'none', redirectUris: ['https://client.example.com/callback', 'fixture-app://oauth'] });
expect(body).not.toHaveProperty('scopes'); // Server default is read.
return Response.json({ clientId, grant: { revision: 1 }, oauthSetup: setup() });
});
expect(result.exitCode).toBe(0);
expect(result.result.status).toBe('registered');
expect(result.requests).toHaveLength(2);
});
test('incomplete successful registration never claims a known result or repeats the mutation', async () => {
const result = await capture(['register', 'fixture-example', '--redirect-uri', 'https://client.example.com/callback'], () => Response.json({}));
expect(result.exitCode).toBe(1);
expect(result.result).toMatchObject({ reason: 'admin_outcome_unknown', stage: 'register', outcome: 'unknown', endpoint: base });
expect(result.result.next_action).toContain('admin clients');
expect(result.requests).toHaveLength(2);
});
test('confidential metadata without a secret is never reported as a delivered private setup', async () => {
const output = join(newDirectory(), 'missing-secret.json');
const artifact = setup(true); delete artifact.client.client_secret;
const result = await capture(['register', 'fixture-example', '--redirect-uri', 'https://client.example.com/callback', '--token-endpoint-auth-method', 'client_secret_post', '--credentials-out', output], () => Response.json({ clientId, oauthSetup: artifact }));
expect(result.exitCode).toBe(1);
expect(result.result).toMatchObject({ reason: 'credential_delivery_incomplete', client_id: clientId });
expect(result.result.next_action).toContain('admin setup');
expect(() => readFileSync(output)).toThrow();
});
test('confidential creation requires an unused private destination before any HTTP mutation', async () => {
const args = ['register', 'fixture-example', '--redirect-uri', 'https://client.example.com/callback', '--token-endpoint-auth-method', 'client_secret_post'];
const missing = await capture(args, () => { throw new Error('unexpected network'); });
expect(missing.requests).toHaveLength(0);
expect(missing.result.reason).toBe('credential_destination_required');
const path = join(newDirectory(), 'occupied.json');
writeFileSync(path, 'do not overwrite', { mode: 0o600 });
const occupied = await capture([...args, '--credentials-out', path], () => { throw new Error('unexpected network'); });
expect(occupied.requests).toHaveLength(0);
expect(readFileSync(path, 'utf8')).toBe('do not overwrite');
});
test('confidential OAuth export is private, redacted on stdout, and rejected as a machine handoff', async () => {
const output = join(newDirectory(), 'oauth.json');
const result = await capture(['register', 'fixture-example', '--redirect-uri', 'https://client.example.com/callback', '--token-endpoint-auth-method', 'client_secret_post', '--credentials-out', output], () =>
Response.json({ clientId, clientSecret: secret, grant: { revision: 1 }, oauthSetup: setup(true) }));
expect(result.exitCode).toBe(0);
const exported = JSON.parse(readFileSync(output, 'utf8'));
expect(exported.client.client_secret).toBe(secret);
expect(exported.kind).toBe('oauth-client-setup');
expect(() => validateCredentials(exported)).toThrow();
if (process.platform !== 'win32') expect(statSync(output).mode & 0o777).toBe(0o600);
expect(result.output).not.toContain(secret);
expect(result.output).not.toContain(owner);
});
test('safe setup never requests secrets until explicit export and passes mixed-client flow', async () => {
const metadata = await capture(['setup', clientId, '--harness', 'generic', '--flow', 'authorization-code'], url => {
expect(url).toContain('/setup?harness=generic&flow=authorization-code');
return Response.json({ status: 'registered', setup: setup(), instructions: ['Authorize in the client'], grant: { revision: 1 } });
});
expect(metadata.requests).toHaveLength(2);
expect(metadata.requests.some(request => request.url.includes('recover-client'))).toBe(false);
const output = join(newDirectory(), 'public-oauth.json');
const exported = await capture(['setup', clientId, '--flow', 'authorization-code', '--credentials-out', output], (url, init) => {
if (url.endsWith('/recover-client')) {
expect(JSON.parse(String(init.body))).toEqual({ clientId, harness: 'generic', flow: 'authorization-code' });
return Response.json({ clientId, oauthSetup: setup() });
}
return Response.json({ status: 'registered', setup: setup(), grant: { revision: 1 }, instructions: [] });
});
expect(exported.requests).toHaveLength(3); // One session for safe setup and private export.
expect(JSON.parse(readFileSync(output, 'utf8')).client).not.toHaveProperty('client_secret');
});
test('lifecycle previews by default; applies only reviewed revisions and reports uncertain responses', async () => {
const preview = await capture(['invalidate-tokens', clientId], (_url, init) => {
expect(JSON.parse(String(init.body))).toEqual({ action: 'invalidate-tokens', dryRun: true });
return Response.json({ action: 'invalidate-tokens', dry_run: true, before: { revision: 4 }, consequences: ['Existing tokens stop working.'] });
});
expect(preview.result.dry_run).toBe(true);
const missingRevision = await capture(['delete', clientId, '--yes'], () => { throw new Error('unexpected network'); });
expect(missingRevision.requests).toHaveLength(0);
expect(missingRevision.result.reason).toBe('revision_required');
const applied = await capture(['revoke', clientId, '--yes', '--if-version', '4'], (_url, init) => {
expect(JSON.parse(String(init.body))).toEqual({ action: 'revoke', dryRun: false, expectedRevision: 4, yes: true });
throw new Error('connection lost');
});
expect(applied.result).toMatchObject({ reason: 'admin_outcome_unknown', outcome: 'unknown' });
expect(applied.result.next_action).toContain(`client ${clientId}`);
expect(applied.requests).toHaveLength(2);
});
test('backend failures stay visible and cannot expose the owner credential', async () => {
const result = await capture(['clients'], () => Response.json({ error: 'service_unavailable', message: `backend unavailable ${owner}` }, { status: 503 }));
expect(result.exitCode).toBe(1);
expect(result.result).toMatchObject({ status: 'error', reason: 'service_unavailable', http_status: 503 });
expect(result.output).not.toContain(owner);
expect(result.result).not.toHaveProperty('clients');
});
test('people administration commands send owner-session requests to the access routes (GST-1094 gap 4)', async () => {
const cases: Array<[string[], string, unknown]> = [
[['attest', clientId, '--attest-actor', 'qm', '--attest-ops', 'memory_recall,memory_write', '--dry-run'], '/admin/api/access/attest', { clientId, dryRun: true, attestActor: 'qm', attestOps: ['memory_recall', 'memory_write'] }],
[['attest', clientId, '--attest-actor', 'none'], '/admin/api/access/attest', { clientId, dryRun: false, attestActor: null }],
[['attest', clientId, '--attest-read', 'person', '--dry-run'], '/admin/api/access/attest', { clientId, dryRun: true, attestRead: 'person' }],
[['attest', clientId, '--attest-read', 'none'], '/admin/api/access/attest', { clientId, dryRun: false, attestRead: null }],
[['members', '--all'], '/admin/api/access/members?all=1', undefined],
[['member-add', 'alice-example', '--name', 'Alice Example', '--groups', 'team-a,team-b'], '/admin/api/access/members', { action: 'add', id: 'alice-example', name: 'Alice Example', groups: ['team-a', 'team-b'] }],
[['member-disable', 'alice-example'], '/admin/api/access/members', { action: 'disable', id: 'alice-example' }],
[['member-enable', 'alice-example'], '/admin/api/access/members', { action: 'enable', id: 'alice-example' }],
[['links', '--member', 'alice-example'], '/admin/api/access/member-links?member=alice-example', undefined],
[['link', 'alice-example', '--qm', 'ext-alice', '--dry-run'], '/admin/api/access/member-links', { action: 'link', externalId: 'ext-alice', dryRun: true, member: 'alice-example' }],
[['unlink', '--qm', 'ext-alice'], '/admin/api/access/member-links', { action: 'unlink', externalId: 'ext-alice', dryRun: false }],
];
for (const [args, path, body] of cases) {
expect(mcpNeedsEngine(['admin', args[0]!], undefined)).toBe(false);
const run = await capture(args, () => Response.json({ applied: false }));
expect(run.exitCode).toBe(0);
const sent = run.requests.at(-1)!;
expect(sent.url).toBe(base + path);
expect(sent.init.body === undefined ? undefined : JSON.parse(String(sent.init.body))).toEqual(body);
expect(run.output).not.toContain(owner);
}
const refused = await capture(['attest', clientId], () => Response.json({}));
expect(refused.result).toMatchObject({ status: 'error', reason: 'invalid_arguments' });
const noQm = await capture(['link', 'alice-example'], () => Response.json({}));
expect(noQm.result).toMatchObject({ status: 'error', reason: 'invalid_arguments' });
const serverRefusal = await capture(['attest', clientId, '--attest-actor', 'qm'], () => Response.json({ error: 'invalid_params', code: 'invalid_params', message: 'not a confidential client-credentials client', outcome: 'failed' }, { status: 400 }));
expect(serverRefusal.result.status).toBe('error');
expect(serverRefusal.exitCode).toBe(1);
});
test('GST-1158: member-add and member-set send a declared email, and link finds the member by --email', async () => {
const cases: Array<[string[], string, unknown]> = [
[['member-add', 'alice-example', '--email', '[email protected]'], '/admin/api/access/members', { action: 'add', id: 'alice-example', email: '[email protected]' }],
[['member-set', 'alice-example', '--email', '[email protected]'], '/admin/api/access/members', { action: 'set', id: 'alice-example', email: '[email protected]' }],
[['member-set', 'alice-example', '--email', 'none'], '/admin/api/access/members', { action: 'set', id: 'alice-example', email: null }],
[['link', '--qm', 'ext-alice', '--email', '[email protected]', '--dry-run'], '/admin/api/access/member-links', { action: 'link', externalId: 'ext-alice', dryRun: true, email: '[email protected]' }],
];
for (const [args, path, body] of cases) {
expect(mcpNeedsEngine(['admin', args[0]!], undefined)).toBe(false);
const run = await capture(args, () => Response.json({ applied: false }));
expect(run.exitCode).toBe(0);
const sent = run.requests.at(-1)!;
expect(sent.url).toBe(base + path);
expect(JSON.parse(String(sent.init.body))).toEqual(body);
expect(run.output).not.toContain(owner);
}
for (const args of [['member-set', 'alice-example'], ['link', 'alice-example', '--qm', 'ext-alice', '--email', '[email protected]'], ['link', '--qm', 'ext-alice']]) {
const refused = await capture(args, () => Response.json({}));
expect(refused.result).toMatchObject({ status: 'error', reason: 'invalid_arguments' });
expect(refused.requests.filter(r => !r.url.endsWith('/admin/login'))).toEqual([]);
}
const notFound = await capture(['link', '--qm', 'ext-nobody', '--email', '[email protected]'], () => Response.json({ error: 'not_found', code: 'not_found', message: 'No member has that email.', outcome: 'failed' }, { status: 400 }));
expect(notFound.result.status).toBe('error');
expect(notFound.exitCode).toBe(1);
});
test('GST-2407: memory-proposals list, show, approve and deny mirror the owner proposal routes, one request id per decision', async () => {
const id = '0f8e2a1c-7b3d-5e9f-8a4b-6c2d1e0f9a8b';
const cases: Array<[string[], string, unknown]> = [
[['memory-proposals', 'list'], '/admin/api/memory-proposals', undefined],
[['memory-proposals', 'list', '--source', 'source-a', '--cursor', 'abc_-'], '/admin/api/memory-proposals?source=source-a&cursor=abc_-', undefined],
[['memory-proposals', 'show', id], '/admin/api/memory-proposals/' + id, undefined],
[['memory-proposals', 'approve', id, '--dry-run'], '/admin/api/memory-proposals/' + id, { action: 'approve', dryRun: true }],
[['memory-proposals', 'approve', id], '/admin/api/memory-proposals/' + id, { action: 'approve', dryRun: false }],
[['memory-proposals', 'deny', id, '--reason', 'Not confirmed'], '/admin/api/memory-proposals/' + id, { action: 'deny', dryRun: false, reason: 'Not confirmed' }],
];
for (const [args, path, body] of cases) {
expect(mcpNeedsEngine(['admin', ...args], undefined)).toBe(false);
const run = await capture(args, () => Response.json({ applied: false }));
expect(run.exitCode).toBe(0);
const sent = run.requests.at(-1)!;
expect(sent.url).toBe(base + path);
expect(sent.init.method).toBe(body === undefined ? 'GET' : 'POST');
expect(sent.init.body === undefined ? undefined : JSON.parse(String(sent.init.body))).toEqual(body);
expect(run.output).not.toContain(owner);
}
for (const args of [['memory-proposals'], ['memory-proposals', 'remove', id], ['memory-proposals', 'approve'], ['memory-proposals', 'approve', id, id],
['memory-proposals', 'approve', id, '--reason', 'because'], ['memory-proposals', 'deny', id], ['memory-proposals', 'list', '--dry-run'], ['memory-proposals', 'show', id, '--source', 'source-a']]) {
_resetCliExitVerdictForTests();
const refused = await capture(args, () => Response.json({}));
expect(refused.result).toMatchObject({ status: 'error' });
expect(['invalid_arguments', 'invalid_admin_command', 'missing_target']).toContain(refused.result.reason);
expect(refused.requests.filter(r => !r.url.endsWith('/admin/login'))).toEqual([]);
expect(refused.exitCode).toBe(1);
}
_resetCliExitVerdictForTests();
const writeFailed = await capture(['memory-proposals', 'approve', id], () => Response.json({ applied: true, status: 'approved', request_id: id, write_request: { state: 'failed', write_error: 'actor_unlinked' }, outcome: 'failed' }));
expect(writeFailed.result).toMatchObject({ status: 'approved', outcome: 'failed', write_request: { state: 'failed' } });
expect(writeFailed.exitCode).toBe(1);
_resetCliExitVerdictForTests();
const closed = await capture(['memory-proposals', 'approve', id], () => Response.json({ error: 'proposal_closed', code: 'proposal_closed', message: 'Proposal is denied.', outcome: 'failed' }, { status: 400 }));
expect(closed.result).toMatchObject({ status: 'error', reason: 'proposal_closed', outcome: 'failed' });
expect(closed.exitCode).toBe(1);
_resetCliExitVerdictForTests();
const unknown = await capture(['memory-proposals', 'deny', id, '--reason', 'no'], () => Response.json({ error: 'administration_unavailable', code: 'administration_unavailable', message: 'The change outcome is unknown.', outcome: 'unknown' }, { status: 503 }));
expect(unknown.result).toMatchObject({ status: 'error', outcome: 'unknown', next_action: 'gbrain mcp admin memory-proposals show ' + id + ' --url ' + base });
expect(unknown.exitCode).toBe(1);
_resetCliExitVerdictForTests();
const preview = await capture(['memory-proposals', 'approve', id, '--dry-run'], () => Response.json({ applied: false, dry_run: true, would: 'failed', error_code: 'actor_unlinked' }));
expect(preview.exitCode).toBe(0);
});