Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.8 KB
Raw Blame
/**
 * Minions-visibility wave — `get_agent_job` MCP op tests (amendment 27,
 * ENG-16/18).
 *
 * Mirrors the `test/submit-agent.test.ts` harness (the file that pins the
 * `__owner_client_id` semantics) and covers the trust boundary:
 *   - ctx.auth.clientId REQUIRED on EVERY transport (absent → permission_denied,
 *     including local ctx.remote === false — closes the stdio/legacy bypass)
 *   - cross-client isolation: client A cannot read client B's job
 *   - foreign vs missing id: uniform not_found envelope (no enumeration oracle)
 *   - agent-lane only: a non-subagent job with a matching id is invisible
 *   - trimmed view: no data/prompt leak in the response
 *   - queue_position: claim-order (priority ASC, created_at ASC) count of
 *     waiting jobs ahead, present ONLY while status = 'waiting'
 *
 * Engine parity note: these run on PGLite. The ownership fence is the plain
 * `data->>'__owner_client_id' = $2` JSONB predicate — byte-identical SQL on
 * both engines and the same expression submit_agent's concurrency cap already
 * exercises; the DATABASE_URL-gated e2e parity suite covers the executeRaw
 * seam on real Postgres.
 */

import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { operationsByName, OperationError } from '../src/core/operations.ts';

const get_agent_job = operationsByName['get_agent_job'];
if (!get_agent_job) {
  throw new Error('get_agent_job op missing from operations registry — test fixture invalid');
}

let engine: PGLiteEngine;

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', '85');
});

function makeCtx(opts: { clientId?: string; remote?: boolean } = {}): any {
  return {
    engine,
    config: {},
    logger: console,
    dryRun: false,
    remote: opts.remote ?? true,
    auth: opts.clientId ? { clientId: opts.clientId } : undefined,
  };
}

/** Insert a minion job row directly; returns the job id. */
async function seedJob(opts: {
  owner?: string;
  name?: string;
  status?: string;
  queue?: string;
  priority?: number;
  createdAtSql?: string;
  errorText?: string | null;
  result?: Record<string, unknown> | null;
}): Promise<number> {
  const data: Record<string, unknown> = { prompt: 'seeded' };
  if (opts.owner) data.__owner_client_id = opts.owner;
  const rows = await engine.executeRaw<{ id: number }>(
    `INSERT INTO minion_jobs (submission_authority, name, status, data, queue, priority, created_at, error_text, result)
     VALUES ('{"version":1,"kind":"application"}'::jsonb, $1, $2, $3::text::jsonb, $4, $5, ${opts.createdAtSql ?? 'now()'}, $6, $7::text::jsonb)
     RETURNING id`,
    [
      opts.name ?? 'subagent',
      opts.status ?? 'waiting',
      JSON.stringify(data),
      opts.queue ?? 'default',
      opts.priority ?? 0,
      opts.errorText ?? null,
      opts.result ? JSON.stringify(opts.result) : null,
    ],
  );
  return Number(rows[0].id);
}

describe('get_agent_job op surface', () => {
  it('declares scope=agent and a required numeric id param', () => {
    expect(get_agent_job.scope).toBe('agent');
    // Agent contract v1 (A2): every op declares its effect; this read is non-mutating.
    expect(get_agent_job.mutating).toBe(false);
    expect((get_agent_job.params.id as any).required).toBe(true);
    expect((get_agent_job.params.id as any).type).toBe('number');
    expect(typeof (get_agent_job.params.id as any).description).toBe('string');
  });
});

describe('client identity requirement (amendment 27 — every transport)', () => {
  it('refuses without ctx.auth.clientId on a remote transport', async () => {
    const id = await seedJob({ owner: 'alice' });
    await expect(get_agent_job.handler(makeCtx({ remote: true }), { id })).rejects.toMatchObject({
      code: 'permission_denied',
    });
  });

  it('refuses without ctx.auth.clientId even when remote === false (closes the stdio/legacy bypass)', async () => {
    const id = await seedJob({ owner: 'alice' });
    await expect(get_agent_job.handler(makeCtx({ remote: false }), { id })).rejects.toMatchObject({
      code: 'permission_denied',
    });
  });
});

describe('cross-client isolation + anti-enumeration', () => {
  it('client A reads its own job', async () => {
    const id = await seedJob({ owner: 'alice' });
    const r = (await get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id })) as any;
    expect(r.id).toBe(id);
    expect(r.status).toBe('waiting');
  });

  it('client A cannot read client B\'s job', async () => {
    const id = await seedJob({ owner: 'bob' });
    await expect(get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id })).rejects.toMatchObject({
      code: 'not_found',
    });
  });

  it('foreign and missing ids produce the SAME envelope (code + message shape)', async () => {
    const foreignId = await seedJob({ owner: 'bob' });
    const missingId = foreignId + 100_000;
    const grab = async (id: number): Promise<OperationError> => {
      try {
        await get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id });
      } catch (e) {
        return e as OperationError;
      }
      throw new Error('expected a throw');
    };
    const foreign = await grab(foreignId);
    const missing = await grab(missingId);
    expect(foreign.code).toBe('not_found');
    expect(missing.code).toBe('not_found');
    // Identical wording modulo the id — no "exists but not yours" tell.
    expect(foreign.message.replace(String(foreignId), 'N')).toBe(
      missing.message.replace(String(missingId), 'N'),
    );
    expect(foreign.suggestion).toBe(missing.suggestion);
  });

  it('agent-lane only: a non-subagent job is invisible even with a matching owner field', async () => {
    const id = await seedJob({ owner: 'alice', name: 'sync' });
    await expect(get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id })).rejects.toMatchObject({
      code: 'not_found',
    });
  });

  it('rejects a non-integer id as invalid_params (caller bug, distinct from not_found)', async () => {
    await expect(
      get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id: 'abc' as any }),
    ).rejects.toMatchObject({ code: 'invalid_params' });
  });
});

describe('trimmed response shape', () => {
  it('returns only the trimmed keys — never data/prompt', async () => {
    const id = await seedJob({
      owner: 'alice',
      status: 'completed',
      errorText: null,
      result: { answer: 42 },
    });
    const r = (await get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id })) as Record<string, unknown>;
    expect(Object.keys(r).sort()).toEqual(
      ['created_at', 'error_text', 'finished_at', 'id', 'result', 'started_at', 'status'].sort(),
    );
    expect(r.result).toEqual({ answer: 42 });
    expect(JSON.stringify(r)).not.toContain('__owner_client_id');
    expect(JSON.stringify(r)).not.toContain('prompt');
  });
});

describe('queue_position (claim-order: priority ASC, created_at ASC)', () => {
  it('counts waiting jobs ahead on the same queue, 0 = next to be claimed', async () => {
    // Claim order: p0-older, p0-newer, p5. Owners differ — position counts
    // ALL waiting competitors, not just the caller's own jobs.
    const first = await seedJob({ owner: 'alice', priority: 0, createdAtSql: "now() - interval '3 minutes'" });
    const second = await seedJob({ owner: 'bob', priority: 0, createdAtSql: "now() - interval '2 minutes'" });
    const third = await seedJob({ owner: 'alice', priority: 5, createdAtSql: "now() - interval '4 minutes'" });

    const r1 = (await get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id: first })) as any;
    expect(r1.queue_position).toBe(0);
    const r2 = (await get_agent_job.handler(makeCtx({ clientId: 'bob' }), { id: second })) as any;
    expect(r2.queue_position).toBe(1);
    // Higher priority NUMBER = claimed later (priority ASC) despite being older.
    const r3 = (await get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id: third })) as any;
    expect(r3.queue_position).toBe(2);
  });

  it('scopes the count to the job\'s own queue', async () => {
    await seedJob({ owner: 'bob', queue: 'other', createdAtSql: "now() - interval '10 minutes'" });
    const id = await seedJob({ owner: 'alice', queue: 'default' });
    const r = (await get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id })) as any;
    expect(r.queue_position).toBe(0);
  });

  it('is absent for non-waiting jobs', async () => {
    const id = await seedJob({ owner: 'alice', status: 'active' });
    const r = (await get_agent_job.handler(makeCtx({ clientId: 'alice' }), { id })) as Record<string, unknown>;
    expect('queue_position' in r).toBe(false);
  });
});