Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import type { SharedSkillFileInput } from '../src/core/shared-skills/model.ts';
import { claimWorktree } from '../src/core/persistence/ownership.ts';
import { activateSharedSkillPersistence } from '../src/core/persistence/skill-activation.ts';
import { declarePersistenceProtocol } from '../src/core/persistence/protocol.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { sha256 } from '../src/core/persistence/digest.ts';
import { adoptSharedSkillpack, submitSharedSkillMutation } from '../src/core/shared-skills/publication.ts';
import { getSharedSkill, getSharedSkillAsset } from '../src/core/shared-skills/catalog.ts';
import { setSharedSkillPolicy } from '../src/core/shared-skills/policy.ts';
import { isolatedSharedSkillsEngine } from './helpers/shared-skills-engine.ts';
import { withEnv } from './helpers/with-env.ts';
const prose = (name: string, body = 'Synthetic prose', depends_on: string[] = []): SharedSkillFileInput => ({
path: `skills/${name}/SKILL.md`, content: `---\nname: ${name}\n---\n${body}\n`, file_class: 'prose', depends_on,
});
interface ReadObservation { requested: unknown; names: string[]; bytes: number; }
interface Fixture {
engine: BrainEngine; root: string; local: OperationContext; editor: OperationContext; incarnation: string;
observed: ReadObservation[]; queries: string[]; observe(): void;
put(ctx: OperationContext, name: string, files: SharedSkillFileInput[]): Promise<Record<string, unknown>>;
}
async function fixture(run: (fixture: Fixture) => Promise<void>) {
const directory = mkdtempSync(join(tmpdir(), 'gbrain-sparse-skill-publication-'));
try {
await withEnv({ GBRAIN_HOME: join(directory, 'home'), DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () => {
const isolated = await isolatedSharedSkillsEngine();
let recording = false;
const observed: ReadObservation[] = []; const queries: string[] = [];
const wrap = (target: BrainEngine): BrainEngine => new Proxy(target, { get(object, property, receiver) {
const original = Reflect.get(object, property, receiver);
if (property === 'transaction') return function<T>(this: BrainEngine, callback: (tx: BrainEngine) => Promise<T>): Promise<T> {
return original.call(this, (tx: BrainEngine) => callback(wrap(tx)));
};
if (property === 'executeRaw') return async function(this: BrainEngine, sql: string, params?: unknown[]) {
const rows = await original.call(this, sql, params);
if (recording) {
queries.push(sql);
if (sql.startsWith('SELECT r.* FROM shared_skill_heads h JOIN shared_skill_revisions r')) {
observed.push({ requested: params?.[3], names: rows.map((row: { name: string }) => row.name), bytes: Buffer.byteLength(JSON.stringify(rows)) });
}
}
return rows;
};
return original;
} });
const engine = wrap(isolated.engine);
try {
const root = join(directory, 'content'); mkdirSync(root);
await engine.executeRaw("UPDATE sources SET local_path=$1 WHERE id='default'", [root]);
await claimWorktree(engine, 'default', root);
await activateSharedSkillPersistence(engine, { confirmQuiesced: true });
await engine.setConfig('mcp.publish_skills', 'true');
const local: OperationContext = { engine, config: { engine: 'pglite' }, sourceId: 'default', remote: false,
dryRun: false, logger: { info() {}, warn() {}, error() {} } };
await setSharedSkillPolicy(local, 'default', { version: 1, enabled: true, classes: ['prose', 'reference', 'asset'], audiences: ['readers'], requirements: [], allow_follow: true }, null);
const operations = ['list_skills', 'get_skill', 'get_skill_asset', 'put_skill', 'delete_skill'];
await engine.executeRaw(`INSERT INTO oauth_clients(client_id,client_name,scope,source_id,allowed_operations,bound_slug_prefixes)
VALUES('sparse-editor','Synthetic scoped editor','read write skill_editor','default',$1::text[],ARRAY['skills/alpha/'])`, [operations]);
const editor: OperationContext = { ...local, remote: true, auth: { token: 'synthetic', clientId: 'sparse-editor', principal: { kind: 'oauth_client', id: 'sparse-editor' },
sourceId: 'default', scopes: ['read', 'write', 'skill_editor'], allowedOperations: operations, boundSlugPrefixes: ['skills/alpha/'] } };
const [source] = await engine.executeRaw<{ incarnation: string }>("SELECT incarnation FROM sources WHERE id='default'");
await run({ engine, root, local, editor, incarnation: source.incarnation, observed, queries,
observe() { observed.length = 0; queries.length = 0; recording = true; },
async put(ctx, name, files) {
const [head] = await engine.executeRaw<{ revision: string }>("SELECT revision FROM shared_skill_heads WHERE source_id='default' AND name=$1", [name]);
return submitSharedSkillMutation(ctx, 'put_skill', { name, pack_id: 'sparse-pack', source_id: 'default', source_incarnation: source.incarnation,
expected_revision: head?.revision ?? null, request_id: randomUUID(), files });
},
});
} finally { await disposePersistenceConsumer(engine); await isolated.close(); }
});
} finally { rmSync(directory, { recursive: true, force: true }); }
}
function manifest(root: string) {
return JSON.parse(readFileSync(join(root, 'skillpack.json'), 'utf8')) as { skills: string[]; shared_skills: { skills: Array<{ name: string; revision: string; files: Array<{ path: string }> }> } };
}
test('publication stores one proposal copy and preserves custom manifest fields with compact per-skill inventory', () => fixture(async f => {
const custom = { license: 'Synthetic license', notes: { text: 'Quoted "fixture"\nwith a second line' } };
await adoptSharedSkillpack(f.local, 'default', { pack_id: 'sparse-pack',
skills: [{ name: 'alpha', pack_id: 'sparse-pack', expected_revision: null, files: [prose('alpha')] }],
initial_files: { 'skillpack.json': JSON.stringify({ name: 'sparse-pack', brain_resident: true, skills: ['skills/alpha'], ...custom }) } });
await f.put(f.local, 'beta', [prose('beta')]);
const published = await f.put(f.editor, 'alpha', [prose('alpha', 'Changed synthetic instructions')]);
const [row] = await f.engine.executeRaw<{ intent: Record<string, any> }>('SELECT intent FROM persistence_requests WHERE request_id=$1::uuid', [published.request_id]);
expect(row.intent).not.toHaveProperty('files');
expect(row.intent).not.toHaveProperty('metadata');
expect(row.intent.original_manifest).not.toHaveProperty('skills');
expect(row.intent.original_manifest).not.toHaveProperty('shared_skills');
expect(row.intent.proposals).toHaveLength(1);
expect(row.intent.proposals[0].files).toHaveLength(1);
const text = readFileSync(join(f.root, 'skillpack.json'), 'utf8');
expect(JSON.parse(text)).toMatchObject(custom);
expect(JSON.parse(text).skills).toEqual(['skills/alpha', 'skills/beta']);
expect(JSON.parse(text).shared_skills.skills).toHaveLength(2);
expect(text.split('\n').filter(line => line.startsWith(' {"name":'))).toHaveLength(2);
}), 120_000);
function expectOnlyReads(f: Fixture, expected: string[]) {
expect(f.observed.length).toBeGreaterThan(0);
for (const read of f.observed) {
expect(Array.isArray(read.requested)).toBe(true);
expect(read.names.every(name => expected.includes(name))).toBe(true);
expect((read.requested as string[]).every(name => expected.includes(name))).toBe(true);
}
}
test('skill-local edits, shared-file removal and recreation read only the target revision bytes', () => fixture(async f => {
const convention = 'skills/conventions/shared.md';
const files = (name: string, body: string) => [prose(name, body, [convention]), { path: convention, content: 'Unchanged shared convention', file_class: 'reference' as const }];
await f.put(f.local, 'alpha', files('alpha', 'Original alpha'));
await f.put(f.local, 'beta', files('beta', 'Unchanged beta'));
for (let index = 0; index < 6; index++) {
const name = `untouched-${index}`;
await f.put(f.local, name, [prose(name, 'Unrelated fixture content. '.repeat(4000))]);
}
const before = manifest(f.root).shared_skills.skills.filter(skill => skill.name !== 'alpha');
const originalFiles = new Map(before.flatMap(skill => skill.files.map(file => [file.path, sha256(readFileSync(join(f.root, file.path)))] as const)));
f.observe();
const changed = await f.put(f.editor, 'alpha', files('alpha', 'Updated alpha'));
expectOnlyReads(f, ['alpha']);
expect(f.observed.flatMap(read => read.names)).toEqual(['alpha', 'alpha']);
expect(f.observed.reduce((bytes, read) => bytes + read.bytes, 0)).toBeLessThan(16 * 1024);
expect(f.queries.some(sql => sql.includes('AS protected_heads'))).toBe(false);
expect(changed.retention).toBeUndefined();
expect(manifest(f.root).shared_skills.skills.filter(skill => skill.name !== 'alpha')).toEqual(before);
for (const [path, hash] of originalFiles) expect(sha256(readFileSync(join(f.root, path)))).toBe(hash);
f.observe();
const detached = await f.put(f.editor, 'alpha', [prose('alpha', 'No shared dependency')]);
expectOnlyReads(f, ['alpha']);
expect(readFileSync(join(f.root, convention), 'utf8')).toBe('Unchanged shared convention');
expect(manifest(f.root).shared_skills.skills.filter(skill => skill.name !== 'alpha')).toEqual(before);
f.observe();
const deleted = await submitSharedSkillMutation(f.editor, 'delete_skill', { name: 'alpha', pack_id: 'sparse-pack', source_id: 'default', source_incarnation: f.incarnation,
expected_revision: detached.revision, request_id: randomUUID() });
expectOnlyReads(f, ['alpha']);
expect(manifest(f.root).shared_skills.skills).toEqual(before);
f.observe();
const recreated = await f.put(f.editor, 'alpha', [prose('alpha', 'Recreated alpha')]);
expectOnlyReads(f, ['alpha']); expect(recreated.revision).not.toBe(deleted.revision);
expect(manifest(f.root).shared_skills.skills.filter(skill => skill.name !== 'alpha')).toEqual(before);
for (const [path, hash] of originalFiles) expect(sha256(readFileSync(join(f.root, path)))).toBe(hash);
}), 120_000);
test('shared changes load every authorized transitive dependent and no unrelated body', () => fixture(async f => {
const outer = 'skills/conventions/outer.md'; const inner = 'skills/conventions/inner.md'; const added = 'skills/conventions/added.md';
const shared = (name: string, next: boolean): SharedSkillFileInput[] => [prose(name, 'Uses shared closure', [outer]),
{ path: outer, content: 'Outer convention', file_class: 'reference', depends_on: [inner] },
{ path: inner, content: next ? 'Changed inner convention' : 'Original inner convention', file_class: 'reference', depends_on: next ? [added] : [] },
...(next ? [{ path: added, content: 'New transitive helper', file_class: 'reference' as const }] : [])];
await f.put(f.local, 'alpha', shared('alpha', false)); await f.put(f.local, 'beta', shared('beta', false));
await f.put(f.local, 'gamma', [prose('gamma', 'Directly uses inner', [inner]), { path: inner, content: 'Original inner convention', file_class: 'reference' }]);
await f.put(f.local, 'untouched', [prose('untouched', 'Unrelated fixture. '.repeat(4000))]);
const unchanged = manifest(f.root).shared_skills.skills.find(skill => skill.name === 'untouched');
const diskBefore = readFileSync(join(f.root, 'skillpack.json'), 'utf8');
f.observe();
await expect(f.put(f.editor, 'alpha', shared('alpha', true))).rejects.toMatchObject({ code: 'permission_denied' });
expectOnlyReads(f, ['alpha']);
expect(readFileSync(join(f.root, 'skillpack.json'), 'utf8')).toBe(diskBefore);
expect(existsSync(join(f.root, added))).toBe(false);
await f.engine.executeRaw("UPDATE oauth_clients SET bound_slug_prefixes=ARRAY['skills/'] WHERE client_id='sparse-editor'");
const editor = { ...f.editor, auth: { ...f.editor.auth!, boundSlugPrefixes: ['skills/'] } };
f.observe();
const result = await f.put(editor, 'alpha', shared('alpha', true));
expectOnlyReads(f, ['alpha', 'beta', 'gamma']);
expect(f.observed.flatMap(read => read.names).sort()).toEqual(['alpha', 'alpha', 'beta', 'beta', 'gamma', 'gamma']);
expect((result.affected_skills as Array<{ name: string }>).map(skill => skill.name).sort()).toEqual(['alpha', 'beta', 'gamma']);
for (const name of ['beta', 'gamma']) {
const detail = await getSharedSkill(editor, { name });
expect(detail.files.map(file => file.path)).toContain(added);
const asset = await getSharedSkillAsset(editor, { ...detail, path: added });
expect(Buffer.from(asset.content, 'base64').toString()).toBe('New transitive helper');
}
expect(manifest(f.root).shared_skills.skills.find(skill => skill.name === 'untouched')).toEqual(unchanged);
f.observe();
await f.put(editor, 'alpha', shared('alpha', false));
expectOnlyReads(f, ['alpha', 'beta', 'gamma']); expect(existsSync(join(f.root, added))).toBe(false);
expect(manifest(f.root).shared_skills.skills.find(skill => skill.name === 'untouched')).toEqual(unchanged);
}), 120_000);
test('an incomplete sealed inventory fails closed rather than dropping an unaffected manifest entry', () => fixture(async f => {
await f.put(f.local, 'alpha', [prose('alpha')]); await f.put(f.local, 'beta', [prose('beta')]);
const diskBefore = readFileSync(join(f.root, 'skillpack.json'), 'utf8');
const damaged = manifest(f.root); damaged.shared_skills.skills = damaged.shared_skills.skills.filter(skill => skill.name !== 'beta');
await f.engine.transaction(async tx => {
await declarePersistenceProtocol(tx);
await withCoordinatedWrite(tx, ['default'], () => tx.executeRaw("UPDATE shared_skill_packs SET manifest=$1::text::jsonb WHERE source_id='default'", [JSON.stringify(damaged)]), TEST_WRITE_ATTRIBUTION);
});
f.observe();
await expect(f.put(f.editor, 'alpha', [prose('alpha', 'Must not commit')])).rejects.toMatchObject({ code: 'revision_conflict' });
expect(f.observed).toEqual([]);
expect(readFileSync(join(f.root, 'skillpack.json'), 'utf8')).toBe(diskBefore);
expect(readFileSync(join(f.root, 'skills/alpha/SKILL.md'), 'utf8')).toBe(prose('alpha').content);
}), 120_000);