Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.1 KB
Raw Blame
/**
 * Submit-time spend authorization on queued paid jobs (PGLite).
 *
 * Protects: the strict record parser, the trusted-only storage path, the
 * claim-time `legacy_default` stamp, the coalesce compare-and-set, the
 * per-acquisition fence trigger, and the worker guard's group metering.
 * Regressions that fail it: a record read from job data, a claim that stamps
 * the wrong rows, an old-protocol claim that runs a spend-authorized row, or
 * a guard that does not reserve against the group.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, spyOn, test } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { MinionQueue } from '../src/core/minions/queue.ts';
import { invokeAI } from '../src/core/ai/invocation-guard.ts';
import { chatInvocation } from '../src/core/ai/guarded-generation.ts';
import {
  jobSpendAuthorization, parseSpendAuthorization, runWithJobSpend, spendBasis, spendSubmitSummary, SpendGroupRefusedError,
  type SpendAuthorization,
} from '../src/core/minions/spend-authorization.ts';
import type { MinionJob, MinionJobContext } from '../src/core/minions/types.ts';
import type { Authorization } from '../src/core/consent.ts';

let engine: PGLiteEngine;
let queue: MinionQueue;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
  queue = new MinionQueue(engine);
});

afterAll(async () => {
  await engine.disconnect();
});

beforeEach(async () => {
  await engine.executeRaw('DELETE FROM mcp_spend_reservations');
  await engine.executeRaw('DELETE FROM mcp_spend_log');
  await engine.executeRaw('DELETE FROM minion_jobs');
});

const auth = (cap: number, source: Authorization['cap_source'] = 'derived'): Authorization =>
  ({ consented_effects: ['paid'], cap_usd: cap, cap_source: source, via: 'yes' });
const record = (cap = 10, source: Authorization['cap_source'] = 'derived', of = 2) =>
  jobSpendAuthorization(auth(cap, source), { command: 'book-mirror', est_usd: cap / 1.5, of, argv: ['gbrain', 'book-mirror', '--slug', 'a-book'] });
const ctxFor = (job: MinionJob) => ({ id: job.id, name: job.name, data: job.data, attempts_made: 0 }) as unknown as MinionJobContext;

/** A priced provider attempt: maximum `maxCents`, actual `actualCents` (claude-sonnet-5 input at $2/Mtok, reserved at 2x). */
const attempt = (maxCents: number, actualCents: number, model = 'anthropic:claude-sonnet-5') => invokeAI(
  { operation: 'test', kind: 'chat', model, maxInputTokens: maxCents * 2500, maxOutputTokens: 0 },
  async () => 'ok', () => ({ inputTokens: actualCents * 5000, outputTokens: 0 }));

async function claimed(name: string, opts: Record<string, unknown> = {}, spend?: SpendAuthorization): Promise<MinionJob> {
  await queue.add(name, { prompt: 'x' }, opts, { allowProtectedSubmit: true, ...(spend ? { spendAuthorization: spend } : {}) });
  const job = await queue.claim('tok', 60_000, 'default', [name]);
  if (!job) throw new Error('nothing claimed');
  return job;
}

describe('spend authorization record', () => {
  test('the parser accepts each kind and rejects malformed or unknown shapes', () => {
    const capped = record();
    expect(parseSpendAuthorization(capped)).toEqual(capped);
    const uncapped = jobSpendAuthorization({ uncapped: true, via: 'max_usd' }, { command: 'enrich', of: 1 });
    expect(parseSpendAuthorization(JSON.stringify(uncapped))).toMatchObject({ cap_usd: null, uncapped: true, cap_source: 'user' });
    expect(parseSpendAuthorization({ version: 1, kind: 'legacy_default', group_id: capped.group_id, cap_usd: 5, cap_source: 'default', command: 'enrich', authorized_at: '2026-10-05T00:00:00.000Z' }))
      .toMatchObject({ kind: 'legacy_default' });
    expect(parseSpendAuthorization(null)).toBeNull();
    for (const bad of [
      { ...capped, kind: 'granted' },
      { ...capped, extra: true },
      { ...capped, cap_usd: null },
      { ...capped, group_id: 'not-a-uuid' },
      { ...capped, cap_usd: -1 },
      [],
    ]) expect(() => parseSpendAuthorization(bad)).toThrow(TypeError);
  });

  test('a record in job data is never read as authorization', async () => {
    const job = await queue.add('enrich', { sourceId: 'default', spend_authorization: record() });
    expect(job.spend_authorization).toBeNull();
    expect(spendBasis(job).basis).toBe('unrecorded');
  });

  test('a malformed column marks the job invalid and the guard refuses to run it', async () => {
    const job = await claimed('subagent', {}, record());
    await engine.executeRaw(`UPDATE minion_jobs SET spend_authorization = '{"version":2}'::jsonb WHERE id = $1`, [job.id]);
    const reread = (await queue.getJob(job.id))!;
    expect(reread.spend_authorization_invalid).toBe(true);
    expect(spendBasis(reread).basis).toBe('invalid');
    await expect(runWithJobSpend(engine, reread, ctxFor(reread), async () => 'ran')).rejects.toThrow('spend_authorization_invalid');
  });
});

describe('claim-time legacy_default', () => {
  test('stamps only NULL rows of the consent-gated producers, with the job-type cap', async () => {
    const rows = [
      ['subagent', 'book-mirror:a-book:ch-1', {}],
      ['enrich', 'enrich:default:abc', { maxCostUsd: 2 }],
      ['enrich', 'cli:enrich:abcd1234', {}],
      ['enrich', 'other:enrich', {}],
      ['subagent', 'enrich:default:x', {}],
    ] as const;
    for (const [name, key, data] of rows) await queue.add(name, { ...data, sourceId: 'default' }, { idempotency_key: key }, { allowProtectedSubmit: true });
    const seen: Record<string, SpendAuthorization | null> = {};
    for (let i = 0; i < rows.length; i++) {
      const job = await queue.claim(`tok-${i}`, 60_000, 'default', ['subagent', 'enrich']);
      seen[job!.idempotency_key!] = job!.spend_authorization ?? null;
    }
    expect(seen['book-mirror:a-book:ch-1']).toMatchObject({ kind: 'legacy_default', cap_usd: 5, cap_source: 'default', command: 'book-mirror' });
    expect(seen['enrich:default:abc']).toMatchObject({ kind: 'legacy_default', cap_usd: 2, command: 'enrich' });
    expect(seen['cli:enrich:abcd1234']).toMatchObject({ kind: 'legacy_default', cap_usd: 5 });
    expect(seen['other:enrich']).toBeNull();
    expect(seen['enrich:default:x']).toBeNull();
    expect(new Set(Object.values(seen).filter(Boolean).map(r => r!.group_id)).size).toBe(3);
  });

  test('a legacy_default subagent runs under the $5 default cap and logs its basis', async () => {
    const job = await claimed('subagent', { idempotency_key: 'book-mirror:a-book:ch-2' });
    const logs: string[] = [];
    const log = spyOn(console, 'log').mockImplementation(((line: string) => { logs.push(String(line)); }) as never);
    try {
      expect(await runWithJobSpend(engine, job, ctxFor(job), async () => { await attempt(300, 100); return 'done'; })).toBe('done');
    } finally { log.mockRestore(); }
    const basis = JSON.parse(logs.find(l => l.includes('job_spend_basis'))!.split('job_spend_basis ')[1]!);
    expect(basis).toMatchObject({ job_id: job.id, basis: 'legacy_default', cap_usd: 5, cap_source: 'default' });
    const holds = await engine.executeRaw<{ budget_key: string; status: string }>('SELECT budget_key, status FROM mcp_spend_reservations');
    expect(holds).toEqual([{ budget_key: `group:${job.spend_authorization!.group_id}`, status: 'settled' }]);
  });
});

describe('coalesce compare-and-set', () => {
  test('NULL and legacy rows adopt the new authorization; an authorized row keeps its own', async () => {
    const key = 'book-mirror:b-book:ch-1';
    const legacy = await queue.add('subagent', { prompt: 'x' }, { idempotency_key: key }, { allowProtectedSubmit: true });
    expect(legacy.spend_authorization).toBeNull();
    const first = record();
    const adopted = await queue.add('subagent', { prompt: 'x' }, { idempotency_key: key }, { allowProtectedSubmit: true, spendAuthorization: first });
    expect(adopted.id).toBe(legacy.id);
    expect(adopted.spend_authorization?.group_id).toBe(first.group_id);
    const second = record(20);
    const kept = await queue.add('subagent', { prompt: 'x' }, { idempotency_key: key }, { allowProtectedSubmit: true, spendAuthorization: second });
    expect(kept.spend_authorization?.group_id).toBe(first.group_id);
    expect((await queue.getJob(legacy.id))!.spend_authorization?.group_id).toBe(first.group_id);
    const { summary, lines } = spendSubmitSummary(second, [kept], ['gbrain', 'book-mirror', '--slug', 'b-book']);
    expect(summary.kept).toEqual([{ group_id: first.group_id, cap_usd: 10, job_ids: [legacy.id] }]);
    expect(lines.join('\n')).toContain(`gbrain jobs cancel --group ${first.group_id}`);
  });

  test('a stamped legacy_default row is re-authorized by a rerun', async () => {
    const job = await claimed('subagent', { idempotency_key: 'book-mirror:c-book:ch-1' });
    await engine.executeRaw(`UPDATE minion_jobs SET status = 'waiting', lock_token = NULL WHERE id = $1`, [job.id]);
    const next = record();
    const adopted = await queue.add('subagent', { prompt: 'x' }, { idempotency_key: 'book-mirror:c-book:ch-1' }, { allowProtectedSubmit: true, spendAuthorization: next });
    expect(adopted.spend_authorization).toMatchObject({ kind: 'authorized', group_id: next.group_id });
  });
});

describe('per-acquisition fence', () => {
  const oldClaim = (id: number, token: string) => engine.executeRaw(
    `UPDATE minion_jobs SET status = 'active', claim_generation = claim_generation + 1, lock_token = $2, attempts_started = attempts_started + 1 WHERE id = $1`,
    [id, token]);

  test('an old-protocol claim of a spend-authorized row is refused; a NULL row is still claimable', async () => {
    const fenced = await queue.add('subagent', { prompt: 'x' }, {}, { allowProtectedSubmit: true, spendAuthorization: record() });
    const open = await queue.add('subagent', { prompt: 'y' }, {}, { allowProtectedSubmit: true });
    await expect(oldClaim(fenced.id, 'old')).rejects.toThrow('Minion spend protocol 1 required');
    await expect(oldClaim(open.id, 'old')).resolves.toBeDefined();
  });

  test('new-worker claim, stall, then an old-worker reclaim is refused', async () => {
    const job = await claimed('subagent', {}, record());
    await engine.executeRaw(`UPDATE minion_jobs SET status = 'waiting', lock_token = NULL WHERE id = $1`, [job.id]);
    await expect(oldClaim(job.id, 'old')).rejects.toThrow('Minion spend protocol 1 required');
    const again = await queue.claim('tok-new', 60_000, 'default', ['subagent']);
    expect(again?.id).toBe(job.id);
  });
});

describe('uncapped records', () => {
  test('reserve nothing', async () => {
    const spend = jobSpendAuthorization({ uncapped: true, via: 'max_usd' }, { command: 'enrich', of: 1 });
    const job = await claimed('subagent', {}, spend);
    let sawSpend = false;
    await runWithJobSpend(engine, job, ctxFor(job), async (ctx) => { sawSpend = ctx.spend?.record.uncapped === true; await attempt(300, 100); });
    expect(sawSpend).toBe(true);
    expect(await engine.executeRaw('SELECT 1 FROM mcp_spend_reservations')).toEqual([]);
  });
});

// Protect registered operator pricing in a user-capped worker, which canonical-only
// tests do not cover. Reverting override loading refuses before IO or fails settlement.
// Uses the existing production invocation guard and isolated PGLite, no new seam.
test('a user-capped job admits and settles a registered zero-price local model', async () => {
  const previous = await engine.getConfig('pricing.overrides');
  await engine.setConfig('pricing.overrides', JSON.stringify({ 'litellm:local-test': { input: 0, output: 0 }, 'llama-server-reranker:local-test': 0 }));
  try {
    const job = await claimed('subagent', {}, record(0.000001, 'user'));
    let calls = 0;
    await runWithJobSpend(engine, job, ctxFor(job), async () => invokeAI(
      { operation: 'test-local', kind: 'chat', model: 'litellm:local-test', maxInputTokens: 10000, maxOutputTokens: 1000 },
      async () => { calls++; return 'ok'; }, () => ({ inputTokens: 900, outputTokens: 40 }),
    ));
    await runWithJobSpend(engine, job, ctxFor(job), async () => invokeAI(
      { operation: 'test-rerank', kind: 'rerank', model: 'llama-server-reranker:local-test', maxInputTokens: 10000 },
      async () => { calls++; return 'ranked'; }, () => ({ inputTokens: 900, outputTokens: 0 }),
    ));
    expect(calls).toBe(2);
    const holds = await engine.executeRaw<{ status: string; actual_cents: string }>('SELECT status, actual_cents FROM mcp_spend_reservations');
    expect(holds).toHaveLength(2);
    expect(holds.every(h => h.status === 'settled' && Number(h.actual_cents) === 0)).toBe(true);
    for (const [model, refusal] of [['anthropic:claude-sonnet-5', 'cost_cap_exceeded'], ['example:unpriced-model', 'no_pricing']]) {
      await expect(runWithJobSpend(engine, job, ctxFor(job), async () => invokeAI(
        { operation: 'test-denied', kind: 'chat', model: model!, maxInputTokens: 10000, maxOutputTokens: 1000 },
        async () => { calls++; return 'unexpected'; }, () => ({ inputTokens: 1, outputTokens: 1 }),
      ))).rejects.toThrow(refusal);
    }
    expect(calls).toBe(2);
  } finally {
    await engine.setConfig('pricing.overrides', previous ?? '{}');
  }
});

// #6990: a registered price with no declared context ceiling (OpenRouter declares none) is not a
// missing price. The refusal names the missing ceiling, never sends the operator back to pricing set.
test('a priced model with no context ceiling refuses as no_context_ceiling under a user cap', async () => {
  const previous = await engine.getConfig('pricing.overrides');
  const model = 'openrouter:anthropic/claude-haiku-5.5';
  await engine.setConfig('pricing.overrides', JSON.stringify({ [model]: { input: 0.1, output: 0.5 } }));
  try {
    const call = chatInvocation('test-openrouter', model, 1000);
    expect(call.maxInputTokens).toBeUndefined();
    const job = await claimed('subagent', {}, record(1, 'user'));
    let calls = 0;
    const refusal = await runWithJobSpend(engine, job, ctxFor(job), async () => invokeAI(call,
      async () => { calls++; return 'unexpected'; }, () => ({ inputTokens: 1, outputTokens: 1 }))).catch(e => e as SpendGroupRefusedError);
    expect(calls).toBe(0);
    expect(refusal).toBeInstanceOf(SpendGroupRefusedError);
    const envelope = (refusal as SpendGroupRefusedError).envelope;
    expect(envelope.code).toBe('no_context_ceiling');
    expect(envelope.message).toContain(model);
    expect(envelope.message).toContain('No provider call was made');
    expect(envelope.docs).toBe('docs/guides/write-refusals.md#no_context_ceiling');
    expect(envelope.fix).toMatchObject({ argv: ['gbrain', 'book-mirror', '--slug', 'a-book', '--yes'], consent: ['paid'], next: 'ask_user',
      verify: { argv: ['gbrain', 'jobs', 'list', '--group', job.spend_authorization!.group_id, '--json'] } });
    const fix = envelope.fix as { user_message?: string; inputs?: Array<{ name: string }> };
    expect(fix.user_message).toContain(model);
    expect(fix.inputs!.map(i => i.name)).toEqual(['context_tokens']);
    await expect(runWithJobSpend(engine, job, ctxFor(job), async () => invokeAI(chatInvocation('test-unpriced', 'openrouter:example/unpriced-model', 1000),
      async () => { calls++; return 'unexpected'; }, () => null))).rejects.toThrow('no_pricing');
    expect(calls).toBe(0);
  } finally {
    await engine.setConfig('pricing.overrides', previous ?? '{}');
  }
});