Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.7 KB
Raw Blame
import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'bun:test';
import { mkdtempSync, rmSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { MinionQueue } from '../src/core/minions/queue.ts';
import { prepareRemoteAgent } from '../src/core/minions/submission-authority.ts';
import { LATEST_VERSION } from '../src/core/migrate.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { withEnv } from './helpers/with-env.ts';
import { operationsByName } from '../src/core/operations.ts';
import { currentDelegationGrant, submissionSnapshot, effectiveDelegation, snapshotFromJob } from '../src/core/minions/delegated-policy.ts';

let engine: PGLiteEngine;
let auditDir: string;
beforeAll(async () => { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); });
afterAll(async () => { await engine.disconnect(); });
beforeEach(async () => {
  await resetPgliteState(engine);
  await engine.setConfig('version', String(LATEST_VERSION));
  auditDir = mkdtempSync(join(tmpdir(), 'gbrain-delegation-test-'));
});
afterEach(() => rmSync(auditDir, { recursive: true, force: true }));

async function seed(opts: { tools?: string[]; prefixes?: string[] | null; cap?: number; source?: string; budget?: number | null } = {}) {
  const source = opts.source ?? 'default';
  const prefixes = opts.prefixes === undefined ? ['wiki/agents/*'] : opts.prefixes;
  await engine.executeRaw(`INSERT INTO oauth_clients
    (client_id,client_name,client_secret_hash,scope,grant_types,redirect_uris,token_endpoint_auth_method,
     source_id,federated_read,bound_tools,bound_source_id,delegated_slug_prefixes,delegated_namespace,bound_max_concurrent,budget_usd_per_day)
    VALUES ('client','client','','agent',ARRAY['client_credentials'],ARRAY[]::text[],'client_secret_post',
     $1,ARRAY[$1]::text[],$2,$1,$3,$4,$5,$6)`,
    [source, opts.tools ?? ['get_page','put_page'], prefixes, prefixes === null ? 'job' : 'prefixes', opts.cap ?? 1, opts.budget ?? null]);
}
function ctx(extra: Record<string, unknown> = {}): any {
  return { engine, config: {}, logger: console, remote: true, dryRun: false,
    auth: { clientId: 'client', principal: { kind: 'oauth_client', id: 'client' }, scopes: ['agent'], sourceId: 'default' }, ...extra };
}
async function submit(params: Record<string, unknown> = {}, context = ctx()): Promise<any> {
  return withEnv({ GBRAIN_AUDIT_DIR: auditDir }, () => operationsByName.submit_agent.handler(context, { prompt: 'read the fixture', ...params }));
}

describe('delegation admission and submitted permission ceiling', () => {
  it('requires an authenticated agent token, including direct handler calls', async () => {
    await seed();
    await expect(submit({}, ctx({ auth: { clientId: 'client', scopes: ['read'] } }))).rejects.toThrow('agent scope');
    await expect(submit({}, ctx({ auth: undefined }))).rejects.toThrow('OAuth client');
    await expect(submit({}, ctx({ remote: false }))).rejects.toThrow('local CLI');
  });
  it('requires the verified principal for both preview and enqueue', async () => {
    await seed();
    for (const dryRun of [false, true]) {
      for (const principal of [undefined, { kind: 'legacy_token', id: 'client' }, { kind: 'oauth_client', id: 'another-client' }]) {
        await expect(submit({}, ctx({ dryRun, auth: { ...ctx().auth, principal } }))).rejects.toThrow('verified OAuth principal');
      }
    }
  });
  it('refuses unknown and revoked clients', async () => {
    await expect(submit()).rejects.toThrow('agent_bindings_invalid: client_deleted');
    await seed();
    await engine.executeRaw("UPDATE oauth_clients SET deleted_at=now() WHERE client_id='client'");
    await expect(submit()).rejects.toThrow('client_revoked');
  });
  it('database boundary rejects incomplete agent bindings', async () => {
    await expect(seed({ tools: [] })).rejects.toThrow('oauth_clients_complete_agent_grant');
  });
  it('rejects removed or unknown registry tools', async () => {
    for (const removed of ['invented_tool', 'file_list', 'file_url']) {
      await engine.executeRaw('DELETE FROM oauth_clients');
      await seed({ tools: [removed] });
      await expect(submit()).rejects.toThrow('delegated_tools_unavailable');
    }
  });
  it('preview validates source and model without inserting work', async () => {
    await seed();
    await expect(submit({ model: 'missing-provider:model' }, ctx({ dryRun: true }))).rejects.toThrow('supported agent');
    await expect(submit({}, ctx({ dryRun: true, auth: { clientId: 'client', scopes: ['agent'], sourceId: 'other' } }))).rejects.toThrow('authenticated_source_changed');
    const rows = await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM minion_jobs');
    expect(rows[0]?.n).toBe(0);
  });
  it('preview shows actual tools, source, paths and explicit unlimited spending', async () => {
    await seed();
    const result = await submit({ allowed_tools: ['get_page'] }, ctx({ dryRun: true }));
    expect(result.resolved_tools).toEqual(['get_page']);
    expect(result.bound_source).toBe('default');
    expect(result.spending).toEqual({ mode: 'unlimited' });
  });
  it('preview and enqueue enforce explicit operation authority without requiring direct scopes', async () => {
    await seed();
    await engine.executeRaw("UPDATE oauth_clients SET allowed_operations=ARRAY['submit_agent','get_page'] WHERE client_id='client'");
    const preview = await submit({}, ctx({ dryRun: true }));
    expect(preview.resolved_tools).toEqual(['get_page']);
    await expect(submit({ allowed_tools: ['put_page'] }, ctx({ dryRun: true }))).rejects.toThrow('delegated_tools_invalid');
    await engine.executeRaw("UPDATE oauth_clients SET allowed_operations=ARRAY['get_page'] WHERE client_id='client'");
    await expect(submit({}, ctx({ dryRun: true }))).rejects.toThrow('delegation_operation_withdrawn');
    await expect(submit()).rejects.toThrow('delegation_operation_withdrawn');
    expect(await engine.executeRaw('SELECT * FROM minion_jobs')).toHaveLength(0);
  });
  it('later operation widening cannot widen a submitted operation ceiling', async () => {
    await seed();
    await engine.executeRaw("UPDATE oauth_clients SET allowed_operations=ARRAY['submit_agent','get_page'] WHERE client_id='client'");
    const original = submissionSnapshot(await currentDelegationGrant(engine, 'client'), {});
    await engine.executeRaw("UPDATE oauth_clients SET allowed_operations=NULL WHERE client_id='client'");
    const effective = await effectiveDelegation(engine, original);
    expect(effective.tools).toEqual(['get_page']);
  });
  it('rejects empty or broadened tool and prefix overrides', async () => {
    await seed();
    for (const params of [{ allowed_tools: [] }, { allowed_tools: ['search'] }, { allowed_slug_prefixes: [] }, { allowed_slug_prefixes: ['wiki/'] }]) {
      await expect(submit(params, ctx({ dryRun: true }))).rejects.toThrow('agent_bindings_invalid');
    }
  });
  it('checks namespace boundaries, including sibling names', async () => {
    await seed({ prefixes: ['wiki/agents/one/'] });
    await expect(submit({ allowed_slug_prefixes: ['wiki/agents/one-two/'] })).rejects.toThrow('delegated_prefixes_invalid');
    const result = await submit({ allowed_slug_prefixes: ['wiki/agents/one/sub/'] }, ctx({ dryRun: true }));
    expect(result.resolved_slug_prefixes).toEqual(['wiki/agents/one/sub/*']);
  });
  it('refuses archived sources before preview or enqueue', async () => {
    await seed();
    await engine.executeRaw("UPDATE sources SET archived=true WHERE id='default'");
    await expect(submit({}, ctx({ dryRun: true }))).rejects.toThrow('source_inactive');
    await expect(submit()).rejects.toThrow('source_inactive');
  });
  it('rejects invalid turn limits', async () => {
    await seed();
    for (const max_turns of [0, -1, 1.5, 101, NaN]) await expect(submit({ max_turns })).rejects.toThrow('max_turns');
  });
  it('atomically admits exactly the configured count across queues', async () => {
    await seed({ cap: 2 });
    const results = await withEnv({ GBRAIN_AUDIT_DIR: auditDir }, () => Promise.allSettled(
      Array.from({ length: 8 }, (_, i) => operationsByName.submit_agent.handler(ctx(), { prompt: `request ${i}`, queue: `queue-${i}` }))));
    expect(results.filter(r => r.status === 'fulfilled')).toHaveLength(2);
    const jobs = await engine.executeRaw<{ data: any }>("SELECT data FROM minion_jobs WHERE name='subagent'");
    expect(jobs).toHaveLength(2);
    expect(jobs[0].data.__delegation_grant.tools).toEqual(['get_page','put_page']);
  });
  it('durable remote authority enforces the client slot without a separate identity option', async () => {
    await seed();
    const snapshot = submissionSnapshot(await currentDelegationGrant(engine, 'client'), {});
    const data = { prompt: 'fixture', allowed_tools: snapshot.tools, allowed_slug_prefixes: snapshot.slugPrefixes,
      source_id: snapshot.sourceId, __owner_client_id: snapshot.clientId, __delegation_grant: snapshot };
    const authority = await prepareRemoteAgent(ctx(), data);
    const queue = new MinionQueue(engine);
    await queue.add('subagent', data, {}, { allowProtectedSubmit: true, submissionAuthority: authority });
    await expect(queue.add('subagent', data, {}, { allowProtectedSubmit: true, submissionAuthority: authority })).rejects.toThrow('quota');
  });
  it('counts delayed and paused jobs against the same owner cap', async () => {
    await seed();
    const first = await submit();
    for (const status of ['delayed','paused','waiting-children','active']) {
      await engine.executeRaw("UPDATE minion_jobs SET status=$1, claim_generation=claim_generation+CASE WHEN $1='active' THEN 1 ELSE 0 END WHERE id=$2", [status, first.id]);
      await expect(submit({ prompt: 'another request' })).rejects.toThrow();
    }
  });
  it('uses an explicit job namespace and refuses prefix overrides', async () => {
    await seed({ prefixes: null });
    await expect(submit({ allowed_slug_prefixes: ['wiki/'] })).rejects.toThrow('job_namespace_cannot_be_overridden');
    const result = await submit();
    const rows = await engine.executeRaw<{ data: any }>('SELECT data FROM minion_jobs WHERE id=$1',[result.id]);
    const effective = await effectiveDelegation(engine, snapshotFromJob(rows[0].data)!, result.id);
    expect(effective.slugPrefixes).toEqual([`wiki/agents/${result.id}/*`]);
  });
  it('current tools and paths intersect the original snapshot', async () => {
    await seed({ tools: ['get_page','put_page'], prefixes: ['wiki/'] });
    const original = submissionSnapshot(await currentDelegationGrant(engine,'client'), { allowed_slug_prefixes: ['wiki/project/'] });
    await engine.executeRaw("UPDATE oauth_clients SET bound_tools=ARRAY['get_page','search'], delegated_slug_prefixes=ARRAY['wiki/project/narrow/'] WHERE client_id='client'");
    const effective = await effectiveDelegation(engine, original);
    expect(effective.tools).toEqual(['get_page']);
    expect(effective.slugPrefixes).toEqual(['wiki/project/narrow/*']);
  });
  it('grant widening does not widen submitted tools, paths or finite budget', async () => {
    await seed({ tools: ['get_page'], prefixes: ['wiki/one/'], budget: 3 });
    const original = submissionSnapshot(await currentDelegationGrant(engine,'client'), {});
    await engine.executeRaw("UPDATE oauth_clients SET bound_tools=ARRAY['get_page','put_page'], delegated_slug_prefixes=ARRAY['wiki/'], budget_usd_per_day=NULL WHERE client_id='client'");
    const effective = await effectiveDelegation(engine, original);
    expect(effective.tools).toEqual(['get_page']);
    expect(effective.slugPrefixes).toEqual(['wiki/one/*']);
    expect(Number(effective.budgetUsdPerDay)).toBe(3);
  });
  it('source changes invalidate a job instead of retargeting it', async () => {
    await seed();
    const original = submissionSnapshot(await currentDelegationGrant(engine,'client'), {});
    await engine.executeRaw("INSERT INTO sources(id,name) VALUES ('another','another')");
    await engine.executeRaw("UPDATE oauth_clients SET source_id='another', bound_source_id='another', federated_read=ARRAY['another'] WHERE client_id='client'");
    await expect(effectiveDelegation(engine,original)).rejects.toThrow('submitted_source_or_brain_changed');
  });
  it('removing delegated read authority invalidates an existing job and preview', async () => {
    await seed();
    const original = submissionSnapshot(await currentDelegationGrant(engine, 'client'), {});
    await expect(engine.executeRaw("UPDATE oauth_clients SET federated_read=ARRAY[]::text[] WHERE client_id='client'")).rejects.toThrow('oauth_clients_complete_agent_grant');
    await engine.executeRaw("UPDATE oauth_clients SET scope='read',federated_read=ARRAY[]::text[] WHERE client_id='client'");
    await expect(effectiveDelegation(engine, original)).rejects.toThrow('delegated_read_source_missing');
    await expect(submit({}, ctx({ dryRun: true }))).rejects.toThrow('delegated_read_source_missing');
  });
  it('legacy or forged job payloads never turn empty tools into a full registry', () => {
    expect(() => snapshotFromJob({ __owner_client_id: 'client', allowed_tools: [], source_id: 'default' })).toThrow('legacy_snapshot_missing');
    expect(() => snapshotFromJob({ __owner_client_id: 'client', __delegation_grant: {} })).toThrow('snapshot_invalid');
  });
  it('legacy host/current brain aliases resolve to the serving brain', async () => {
    await seed();
    await engine.executeRaw("UPDATE oauth_clients SET bound_brain_id='host' WHERE client_id='client'");
    const legacy = snapshotFromJob({ __owner_client_id: 'client', allowed_tools: ['get_page'], source_id: 'default', brain_id: 'current' })!;
    const effective = await effectiveDelegation(engine, legacy, 42);
    expect(effective.brainId).toBeNull();
    expect(effective.slugPrefixes).toEqual(['wiki/agents/42/*']);
  });
});